* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual @ 2011-10-26 11:43 Eli Zaretskii 2011-10-26 14:17 ` Stefan Monnier 2011-10-26 14:23 ` martin rudalics 0 siblings, 2 replies; 19+ messages in thread From: Eli Zaretskii @ 2011-10-26 11:43 UTC (permalink / raw) To: 9875 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) ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 11:43 bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Eli Zaretskii @ 2011-10-26 14:17 ` Stefan Monnier 2011-10-26 18:31 ` Eli Zaretskii 2011-10-26 14:23 ` martin rudalics 1 sibling, 1 reply; 19+ messages in thread From: Stefan Monnier @ 2011-10-26 14:17 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 14:17 ` Stefan Monnier @ 2011-10-26 18:31 ` Eli Zaretskii 2011-10-26 22:21 ` Stefan Monnier 0 siblings, 1 reply; 19+ messages in thread From: Eli Zaretskii @ 2011-10-26 18:31 UTC (permalink / raw) To: Stefan Monnier; +Cc: 9875 > From: Stefan Monnier <monnier@iro.umontreal.ca> > Cc: 9875@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? ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 18:31 ` Eli Zaretskii @ 2011-10-26 22:21 ` Stefan Monnier 2011-10-27 7:27 ` Eli Zaretskii 0 siblings, 1 reply; 19+ messages in thread From: Stefan Monnier @ 2011-10-26 22:21 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 >> 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 22:21 ` Stefan Monnier @ 2011-10-27 7:27 ` Eli Zaretskii 2011-10-27 9:56 ` martin rudalics 2011-10-27 12:35 ` Stefan Monnier 0 siblings, 2 replies; 19+ messages in thread From: Eli Zaretskii @ 2011-10-27 7:27 UTC (permalink / raw) To: Stefan Monnier; +Cc: 9875 > From: Stefan Monnier <monnier@iro.umontreal.ca> > Cc: 9875@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. ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 7:27 ` Eli Zaretskii @ 2011-10-27 9:56 ` martin rudalics 2011-10-27 11:05 ` Eli Zaretskii 2011-10-27 12:35 ` Stefan Monnier 1 sibling, 1 reply; 19+ messages in thread From: martin rudalics @ 2011-10-27 9:56 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 9:56 ` martin rudalics @ 2011-10-27 11:05 ` Eli Zaretskii 2011-10-27 12:36 ` Stefan Monnier 2011-10-27 13:16 ` martin rudalics 0 siblings, 2 replies; 19+ messages in thread From: Eli Zaretskii @ 2011-10-27 11:05 UTC (permalink / raw) To: martin rudalics; +Cc: 9875 > Date: Thu, 27 Oct 2011 11:56:16 +0200 > From: martin rudalics <rudalics@gmx.at> > CC: Stefan Monnier <monnier@iro.umontreal.ca>, 9875@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. ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 11:05 ` Eli Zaretskii @ 2011-10-27 12:36 ` Stefan Monnier 2011-10-27 12:58 ` Eli Zaretskii 2011-10-27 13:16 ` martin rudalics 1 sibling, 1 reply; 19+ messages in thread From: Stefan Monnier @ 2011-10-27 12:36 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 12:36 ` Stefan Monnier @ 2011-10-27 12:58 ` Eli Zaretskii 0 siblings, 0 replies; 19+ messages in thread From: Eli Zaretskii @ 2011-10-27 12:58 UTC (permalink / raw) To: Stefan Monnier; +Cc: 9875 > From: Stefan Monnier <monnier@iro.umontreal.ca> > Cc: martin rudalics <rudalics@gmx.at>, 9875@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... ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 11:05 ` Eli Zaretskii 2011-10-27 12:36 ` Stefan Monnier @ 2011-10-27 13:16 ` martin rudalics 1 sibling, 0 replies; 19+ messages in thread From: martin rudalics @ 2011-10-27 13:16 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 7:27 ` Eli Zaretskii 2011-10-27 9:56 ` martin rudalics @ 2011-10-27 12:35 ` Stefan Monnier 1 sibling, 0 replies; 19+ messages in thread From: Stefan Monnier @ 2011-10-27 12:35 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > That sounds mysterious, since it remains unclear what kind of thing is > this "parent". Sorry, I meant "parent window". Stefan ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 11:43 bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Eli Zaretskii 2011-10-26 14:17 ` Stefan Monnier @ 2011-10-26 14:23 ` martin rudalics 2011-10-26 18:54 ` Eli Zaretskii 1 sibling, 1 reply; 19+ messages in thread From: martin rudalics @ 2011-10-26 14:23 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 14:23 ` martin rudalics @ 2011-10-26 18:54 ` Eli Zaretskii 2011-10-27 9:52 ` martin rudalics 0 siblings, 1 reply; 19+ messages in thread From: Eli Zaretskii @ 2011-10-26 18:54 UTC (permalink / raw) To: martin rudalics; +Cc: 9875 > Date: Wed, 26 Oct 2011 16:23:05 +0200 > From: martin rudalics <rudalics@gmx.at> > CC: 9875@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. ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-26 18:54 ` Eli Zaretskii @ 2011-10-27 9:52 ` martin rudalics 2011-10-27 11:00 ` Eli Zaretskii 0 siblings, 1 reply; 19+ messages in thread From: martin rudalics @ 2011-10-27 9:52 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 >> > 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 9:52 ` martin rudalics @ 2011-10-27 11:00 ` Eli Zaretskii 2011-10-27 13:16 ` martin rudalics 2011-10-28 8:04 ` Juri Linkov 0 siblings, 2 replies; 19+ messages in thread From: Eli Zaretskii @ 2011-10-27 11:00 UTC (permalink / raw) To: martin rudalics; +Cc: 9875 > Date: Thu, 27 Oct 2011 11:52:38 +0200 > From: martin rudalics <rudalics@gmx.at> > CC: 9875@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. ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 11:00 ` Eli Zaretskii @ 2011-10-27 13:16 ` martin rudalics 2011-10-28 8:04 ` Juri Linkov 1 sibling, 0 replies; 19+ messages in thread From: martin rudalics @ 2011-10-27 13:16 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 >> 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 ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-27 11:00 ` Eli Zaretskii 2011-10-27 13:16 ` martin rudalics @ 2011-10-28 8:04 ` Juri Linkov 2011-10-28 9:43 ` Eli Zaretskii 2011-10-28 13:38 ` Drew Adams 1 sibling, 2 replies; 19+ messages in thread From: Juri Linkov @ 2011-10-28 8:04 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 9875 > 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. ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-28 8:04 ` Juri Linkov @ 2011-10-28 9:43 ` Eli Zaretskii 2011-10-28 13:38 ` Drew Adams 1 sibling, 0 replies; 19+ messages in thread From: Eli Zaretskii @ 2011-10-28 9:43 UTC (permalink / raw) To: Juri Linkov; +Cc: 9875 > From: Juri Linkov <juri@jurta.org> > Cc: martin rudalics <rudalics@gmx.at>, 9875@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. ^ permalink raw reply [flat|nested] 19+ messages in thread
* bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual 2011-10-28 8:04 ` Juri Linkov 2011-10-28 9:43 ` Eli Zaretskii @ 2011-10-28 13:38 ` Drew Adams 1 sibling, 0 replies; 19+ messages in thread From: Drew Adams @ 2011-10-28 13:38 UTC (permalink / raw) To: 'Juri Linkov', 'Eli Zaretskii'; +Cc: 9875 > 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.) ^ permalink raw reply [flat|nested] 19+ messages in thread
end of thread, other threads:[~2011-10-28 13:38 UTC | newest] Thread overview: 19+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2011-10-26 11:43 bug#9875: 24.0.90; Confusing description of the "window tree" in ELisp manual Eli Zaretskii 2011-10-26 14:17 ` Stefan Monnier 2011-10-26 18:31 ` Eli Zaretskii 2011-10-26 22:21 ` Stefan Monnier 2011-10-27 7:27 ` Eli Zaretskii 2011-10-27 9:56 ` martin rudalics 2011-10-27 11:05 ` Eli Zaretskii 2011-10-27 12:36 ` Stefan Monnier 2011-10-27 12:58 ` Eli Zaretskii 2011-10-27 13:16 ` martin rudalics 2011-10-27 12:35 ` Stefan Monnier 2011-10-26 14:23 ` martin rudalics 2011-10-26 18:54 ` Eli Zaretskii 2011-10-27 9:52 ` martin rudalics 2011-10-27 11:00 ` Eli Zaretskii 2011-10-27 13:16 ` martin rudalics 2011-10-28 8:04 ` Juri Linkov 2011-10-28 9:43 ` Eli Zaretskii 2011-10-28 13:38 ` Drew Adams
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).