Windows' "split status"

Windows' "split status"

[Chong Yidong]

IIUC the window-splits mechanism properly, it goes to a bit of trouble
to record the current value of `window-splits' in each window, when that
window is split off.  This recorded value is retrieved when the window
is resized or deleted.

Why?  Why not just refer to the `window-splits' variable?  Since
`window-splits' is a user option, I don't see any reason to regard it as
a "sticky" property of a window.  Even if the user happens to change the
value of `window-splits' midway through an Emacs session (which is a
corner case anyway), there's nothing wrong with simply handling existing
split windows using the new value, rather than whatever historical
values of `window-splits' they possess.

Re: Windows' "split status"

[martin rudalics]

 > IIUC the window-splits mechanism properly, it goes to a bit of trouble
 > to record the current value of `window-splits' in each window, when that
 > window is split off.  This recorded value is retrieved when the window
 > is resized or deleted.
 >
 > Why?  Why not just refer to the `window-splits' variable?  Since
 > `window-splits' is a user option, I don't see any reason to regard it as
 > a "sticky" property of a window.  Even if the user happens to change the
 > value of `window-splits' midway through an Emacs session (which is a
 > corner case anyway), there's nothing wrong with simply handling existing
 > split windows using the new value, rather than whatever historical
 > values of `window-splits' they possess.

Initially I didn't store that value.  But binding `window-splits' to
non-nil can be useful when you want to show with one command many
buffers on the same frame like in `Buffer-menu-select'.  If you think
it's not useful, I can easily restore the older version where I just
look at the value of `window-splits' (`Buffer-menu-select' could use
`balance-windows' as well).

martin

Re: Windows' "split status"

[Chong Yidong]

martin rudalics <rudalics@gmx.at> writes:

> Initially I didn't store that value.  But binding `window-splits' to
> non-nil can be useful when you want to show with one command many
> buffers on the same frame like in `Buffer-menu-select'.

It might be useful for arranging windows when they are initially
created, for the purpose of distributing them with equal heights/widths.
But it's a bit unexpected for that to "stick around" and affect
subsequent window resizing/deletion commands.  If the user wants that,
she should just set the variable.

> If you think it's not useful, I can easily restore the older version
> where I just look at the value of `window-splits'
> (`Buffer-menu-select' could use `balance-windows' as well).

Just using the value of `window-splits' would be better, yes.  Thanks.

(If in the future it turns out that we need this feature for something,
it would probably be better to reimplement it as a window parameter; I
don't think we need a special slot for it.)

Re: Windows' "split status"

[martin rudalics]

 > It might be useful for arranging windows when they are initially
 > created, for the purpose of distributing them with equal heights/widths.
 > But it's a bit unexpected for that to "stick around" and affect
 > subsequent window resizing/deletion commands.  If the user wants that,
 > she should just set the variable.

Actually I forgot why precisely I wanted them to "stick around".

 > Just using the value of `window-splits' would be better, yes.  Thanks.

Done.

 > (If in the future it turns out that we need this feature for something,
 > it would probably be better to reimplement it as a window parameter; I
 > don't think we need a special slot for it.)

Agreed.

martin

Re: Windows' "split status"

[Chong Yidong]

martin rudalics <rudalics@gmx.at> writes:

>> It might be useful for arranging windows when they are initially
>> created, for the purpose of distributing them with equal heights/widths.
>> But it's a bit unexpected for that to "stick around" and affect
>> subsequent window resizing/deletion commands.  If the user wants that,
>> she should just set the variable.
>
> Actually I forgot why precisely I wanted them to "stick around".
>
>> Just using the value of `window-splits' would be better, yes.
>
> Done.

Thank you.

What about the nest status?  Is there any reason that needs to stick
around?

Re: Windows' "split status"

[martin rudalics]

 > What about the nest status?  Is there any reason that needs to stick
 > around?

To avoid that recombine_windows removes a parent window that glues
windows together.  That's needed for implementing atomic and side
windows which then would work only with `window-nest' permanently t.

We could remove the defcustom for `window-nest' if you think it
contradicts the programmed use of this variable.

martin

Re: Windows' "split status"

[Chong Yidong]

martin rudalics <rudalics@gmx.at> writes:

>> What about the nest status?  Is there any reason that needs to stick
>> around?
>
> To avoid that recombine_windows removes a parent window that glues
> windows together.  That's needed for implementing atomic and side
> windows which then would work only with `window-nest' permanently t.

OK, I see.

How about a variation on this scheme: introduce a `max-children' window
parameter which, if non-nil, determines the maximum number of children
that a window can have (relevant only for internal windows).  For atomic
and side windows, this window parameter would be explicitly set to 2.
When the window parameter is nil or absent, the actual value would be
determined by a user option `window-max-children'.

That would make the behavior more explicit, I think.

Re: Windows' "split status"

[martin rudalics]

 > How about a variation on this scheme: introduce a `max-children' window
 > parameter which, if non-nil, determines the maximum number of children
 > that a window can have (relevant only for internal windows).  For atomic
 > and side windows, this window parameter would be explicitly set to 2.
 > When the window parameter is nil or absent, the actual value would be
 > determined by a user option `window-max-children'.
 >
 > That would make the behavior more explicit, I think.

Do I understand correctly that you want to get rid of the "nest" slot in
the window structur?  The problem with window parameters is that I
currently do save them together with a window configuration and restore
them when restoring the configuration.  Earlier, Stefan didn't want to
do that and I'd like to revert the current behavior at any time when
problems arise.  This would mean, however, that when you have a nested
window, dissolve it within a window excursion, and restore the initial
configuration, the nesting would get lost.  So I'd rather be on the safe
side in this regard.

OTOH, it's not entirely trivial to handle `window-max-children' during
recombination.  Suppose you have a configuration like

  -------------------
|    |    | W3 | W4 |
| W1 | W2 |---------|
|    |    |    W5   |
  -------------------

the user has set `window-max-children' to 3 and deletes W5.  How should
recombine_windows proceed?

martin

Re: Windows' "split status"

[Chong Yidong]

martin rudalics <rudalics@gmx.at> writes:

> The problem with window parameters is that I currently do save them
> together with a window configuration and restore them when restoring
> the configuration.  Earlier, Stefan didn't want to do that and I'd
> like to revert the current behavior at any time when problems arise.
> This would mean, however, that when you have a nested window, dissolve
> it within a window excursion, and restore the initial configuration,
> the nesting would get lost.  So I'd rather be on the safe side in this
> regard.

Not a problem; if we do revert the behavior, we can bring back the
special slot and the old code.  I'd rather we try to DTRT now.

> OTOH, it's not entirely trivial to handle `window-max-children' during
> recombination.  Suppose you have a configuration like
>
>  -------------------
> |    |    | W3 | W4 |
> | W1 | W2 |---------|
> |    |    |    W5   |
>  -------------------
>
> the user has set `window-max-children' to 3 and deletes W5.  How should
> recombine_windows proceed?

If I understand your example, this corresponds to the window tree

       root (internal)
        |
   ----------
  |     |    |
  W1    W2   W6 (internal)
             |
         ---------
         |       |
        W5     --W7 (internal)
               |    |
              W3    W4

On deleting W5 with `window-max-children' of 3, the tree becomes

       root (internal)
        |
   ----------
  |     |    |
  W1    W2   W7 (internal)
             |
          ------
          |    |
         W3    W4

which is reasonable.

As for the case where `window-max-children' has been set to 2 (e.g. by
changing the option midway through an Emacs session), that can be
handled by treating it as a soft limit: Emacs will not *add* children to
an internal window past the number specified by `window-max-children'
(or the window parameter), but if an internal window winds up with
excess children for any reason, Emacs does not try to prune it or
rearrange the window tree.

Does that make sense?

Re: Windows' "split status"

[martin rudalics]

 > Not a problem; if we do revert the behavior, we can bring back the
 > special slot and the old code.  I'd rather we try to DTRT now.

I'm not sure what the TRT is here.  But if we later decide that a slot
is the wrong thing, we can at any time turn "nest" into a parameter
(maybe together with "dedicated" and "fixed-size").  Our experience with
parameters is still meager and I wouldn't want to destabilize the
current code more than necessary.

 > Emacs will not *add* children to
 > an internal window past the number specified by `window-max-children'
 > (or the window parameter), but if an internal window winds up with
 > excess children for any reason, Emacs does not try to prune it or
 > rearrange the window tree.
 >
 > Does that make sense?

For me it's neither trivial to understand nor trivial to implement.  So
I'd be very glad if you gave it a stab.  You can't break much - earlier
Emacsen always failed to recombine the windows from my example.

But I wonder where and how people would want to use such a variable.

martin

Re: Windows' "split status"

[Chong Yidong]

martin rudalics <rudalics@gmx.at> writes:

> But I wonder where and how people would want to use such a variable.

For the same reason they'd use `window-nest'.

My problem with `window-nest' is that the term is misleading: windows
can still be "nested" even when `window-nest' is nil, in the sense that
groups of live windows are nested within internal parent windows.  A
non-nil `window-nest' only means that a parent window can have only two
children.

That's why I think it's better to replace the "window nest status"
concept with something like "the number of allowed children", which is
more direct.  Then there's no reason to limit to a binary choice between
having two children and having unlimited children; we might as well
specify the number of children as an arbitrary integer > 1.

An alternative term might be window-combination-max-size.

I don't care so much about the issue of whether to implement this with a
window parameter rather than a special slot.  The former seems
conceptually cleaner, but the latter is fine if you think it's
technically simpler.

> For me it's neither trivial to understand nor trivial to implement.
> So I'd be very glad if you gave it a stab.  You can't break much -
> earlier Emacsen always failed to recombine the windows from my
> example.

I'll take a look, though there are other a couple of other tasks I have
to handle before getting to it.

Re: Windows' "split status"

[Stefan Monnier]

> My problem with `window-nest' is that the term is misleading: windows
> can still be "nested" even when `window-nest' is nil, in the sense that
> groups of live windows are nested within internal parent windows.  A
> non-nil `window-nest' only means that a parent window can have only two
> children.

But I think this result is just a consequence of the implementation
rather than actual intention.  My impression is that window-nest is
trying to solve a problem which can't be solved with a user-config: it's
trying to provide some kind of way for elisp packages to use parent
windows as a form of "very lightweight sub-frame", without touching much
of their code (e.g. without making their code use parent windows
explicitly).
IIUC the use of window-nest for that purpose only works if the
application limits itself to using 2 windows within that "sub-frame", so
it's not ideal.

> That's why I think it's better to replace the "window nest status"
> concept with something like "the number of allowed children", which is
> more direct.

But I think it goes even further away from the actual intention and need
of (elisp) users.

I can't think of any case where you'd want to set this to a value
greater than 2, for example.


        Stefan

Re: Windows' "split status"

[martin rudalics]

 > My problem with `window-nest' is that the term is misleading: windows
 > can still be "nested" even when `window-nest' is nil, in the sense that
 > groups of live windows are nested within internal parent windows.

Agreed.

 > A non-nil `window-nest' only means that a parent window can have only two
 > children.

Note that "nesting" means two things: To make a parent window when
splitting "in the same direction" and to makes sure that that parent
window is persistent.  Also, nesting can be done in two ways: Either via
the option `window-nest' or via `set-window-nest'.  If you use the
option, you get a two windows nesting right after a split.  If you then
split one of these windows with window-nest nil, you get a nest with
three windows.  With `set-window-nest' you can produce a nest of three
or more windows "a posteriori", that is, a long time after they have
been split off.

 > That's why I think it's better to replace the "window nest status"
 > concept with something like "the number of allowed children", which is
 > more direct.  Then there's no reason to limit to a binary choice between
 > having two children and having unlimited children; we might as well
 > specify the number of children as an arbitrary integer > 1.

Yes.  But I'm afraid of the consequences of this.  In particular if the
variable gets let-bound in between.

 > An alternative term might be window-combination-max-size.

It would be a better name.  Can't you think of a similar term which
doesn't imply a numerical value?

 > I don't care so much about the issue of whether to implement this with a
 > window parameter rather than a special slot.  The former seems
 > conceptually cleaner, but the latter is fine if you think it's
 > technically simpler.

I usually adhered to the following principle: Whatever can be handled on
the Elisp level should be done via parameters.  Slots are used wherever
C code is involved.  `window-splits' was an exception because that
option was previously implemented as a special value of `window-nest'.
The buffer history slots (prev_buffers, next_buffers) are an exception
because they are updated from Fset_window_buffer and initially I was a
bit afraid that messing around with these lists could lead to
unpredictable behavior.  Now I'm quite positive that implementing them
via parameters would be sufficiently safe.

martin

Re: Windows' "split status"

[martin rudalics]

 > But I think this result is just a consequence of the implementation
 > rather than actual intention.  My impression is that window-nest is
 > trying to solve a problem which can't be solved with a user-config: it's
 > trying to provide some kind of way for elisp packages to use parent
 > windows as a form of "very lightweight sub-frame", without touching much
 > of their code (e.g. without making their code use parent windows
 > explicitly).
 > IIUC the use of window-nest for that purpose only works if the
 > application limits itself to using 2 windows within that "sub-frame",

What makes you think that?  You can let-bind `window-nest' to t around a
split and get an extra parent around the resulting two windows.  After
that you can split those windows any which way you want and can get an
arbitrary number of windows within a "sub-frame".  The manual explicitly
uses the term "always" in the sentence

      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.

 > so
 > it's not ideal.

`window-nest' is aimed at providing a safe low-level mechanism to
construct and preserve parent windows.  Everything else can be easily
built in Elisp on top of that, like atomic or side windows.

martin

Re: Windows' "split status"

[monnier]

>> But I think this result is just a consequence of the implementation
>> rather than actual intention.  My impression is that window-nest is
>> trying to solve a problem which can't be solved with a user-config: it's
>> trying to provide some kind of way for elisp packages to use parent
>> windows as a form of "very lightweight sub-frame", without touching much
>> of their code (e.g. without making their code use parent windows
>> explicitly).
>> IIUC the use of window-nest for that purpose only works if the
>> application limits itself to using 2 windows within that "sub-frame",

> What makes you think that?

Are you saying that my description of the intention behind window-nest
is wrong?  Or are you only saying that the "at most 2" limitation is not
really true. while everything else is right?

I don't actually know what was the intention behind window-nest, so
confirmation would be welcome.

> You can let-bind `window-nest' to t around a
> split and get an extra parent around the resulting two windows.  After
> that you can split those windows any which way you want and can get an
> arbitrary number of windows within a "sub-frame".  The manual explicitly
> uses the term "always" in the sentence

That sounds like a rather round-about way to do things (because you have
let-bind the var around some parts of he code, but not all): wouldn't it
be easier to start with "create a parent window" (which would start
containing only the selected window) an then proceed to split it the
usual way.  That would save you from using let-binding.

> `window-nest' is aimed at providing a safe low-level mechanism to
> construct and preserve parent windows.  Everything else can be easily
> built in Elisp on top of that, like atomic or side windows.

If it's a low-level mechanism, why is it a defcustom, then?
If it's aimed at "construct and preserve", why is it a variable, rather
than a function?


        Stefan

Re: Windows' "split status"

[Juri Linkov]

>> An alternative term might be window-combination-max-size.
>
> It would be a better name.  Can't you think of a similar term which
> doesn't imply a numerical value?

`window-combination-constraint'.  Such a general name could define any
restrictions: `t' to always create a new internal window; a number
to limit the number of children; even a predicate function when necessary.
This also will reduce the diversity of window terminology by removing
the term `window nest' in favor of `window combination'.

Re: Windows' "split status"

[Chong Yidong]

Juri Linkov <juri@jurta.org> writes:

>>> An alternative term might be window-combination-max-size.
>>
>> It would be a better name.  Can't you think of a similar term which
>> doesn't imply a numerical value?
>
> `window-combination-constraint'.  Such a general name could define any
> restrictions: `t' to always create a new internal window; a number
> to limit the number of children; even a predicate function when necessary.
> This also will reduce the diversity of window terminology by removing
> the term `window nest' in favor of `window combination'.

Good idea, but I think `window-combination-limit' fits existing Emacs
terminology better.  We could let a value of `t' have the binary window
tree behavior for now, and defer numerical values for post-release.

Re: Windows' "split status"

[martin rudalics]

> Good idea, but I think `window-combination-limit' fits existing Emacs
> terminology better.  We could let a value of `t' have the binary window
> tree behavior for now, and defer numerical values for post-release.

Applied.  Please check.

Thanks, martin

Re: Windows' "split status"

[Stefan Monnier]

> Good idea, but I think `window-combination-limit' fits existing Emacs
> terminology better.  We could let a value of `t' have the binary window
> tree behavior for now, and defer numerical values for post-release.

I still don't understand in which circumstance you'd want a limit other
than "2" or "infinity".


        Stefan

Re: Windows' "split status"

[Juri Linkov]

> Good idea, but I think `window-combination-limit' fits existing Emacs
> terminology better.  We could let a value of `t' have the binary window
> tree behavior for now, and defer numerical values for post-release.

Also I think `window-splits' is a bad name too.  It's vague
and provides no hint of its purpose.  Would it be possible
to find a better name that mentions `combination'?  Such as e.g.
`window-combination-resize' or `window-combination-balance'?

Re: Windows' "split status"

[martin rudalics]

 > Also I think `window-splits' is a bad name too.  It's vague
 > and provides no hint of its purpose.  Would it be possible
 > to find a better name that mentions `combination'?  Such as e.g.
 > `window-combination-resize' or `window-combination-balance'?

The term "balance" would be misleading since `balance-windows' and
`balance-windows-area' both try to give windows the same size which
`window-splits' doesn't.  It rather causes windows get resized
proportionally.  So I changed this to `window-combination-resize'.

Thanks, martin

Re: Windows' "split status"

[Nix]

On 15 Nov 2011, martin rudalics told this:
> What makes you think that?  You can let-bind `window-nest' to t around a
> split and get an extra parent around the resulting two windows.  After
> that you can split those windows any which way you want and can get an
> arbitrary number of windows within a "sub-frame".  The manual explicitly
> uses the term "always" in the sentence
>
>      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.

As a native English speaker, I'm afraid that this reads like a
non-native-English-speaker's attempt to render

> If this variable is always non-`nil', a frame's window tree is always
> a binary tree so every window but the frame's root window has exactly
> one sibling.

which unfortunately has a quite different meaning. While your
formulation is grammatically correct, I don't think it's very meaningful
to talk about a variable's value "always" being something.

Perhaps framing this in terms of a guarantee is clearer?

> If this variable's value remains non-`nil' throughout the lifetime of
> a frame, the frame's window tree is guaranteed to be a binary tree;
> every window nested below the root window will have exactly one
> sibling.

-- 
NULL && (void)

Re: Windows' "split status"

[martin rudalics]

 >>      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.
 >
 > As a native English speaker, I'm afraid that this reads like a
 > non-native-English-speaker's attempt to render
 >
 >> If this variable is always non-`nil', a frame's window tree is always
 >> a binary tree so every window but the frame's root window has exactly
 >> one sibling.

Because of the missing "always"?  Then your formulation is missing yet
another "always" immediately before "exactly".

 > which unfortunately has a quite different meaning.

Mixing temporal operators and quantification in prose is problematic.
But what precisely constitutes the "different meaning" here in your
opinion?

 > While your
 > formulation is grammatically correct, I don't think it's very meaningful
 > to talk about a variable's value "always" being something.

The term "always" has very contrived semantics but it's informally often
used to say something like: If this variable is non-nil when Emacs
starts and is non-nil whenever Emacs performs an action, then for any of
Emacs' frames, that frame's window tree is a binary tree when Emacs
starts and after any action performed by Emacs.  Or, if this variable is
always non-nil, then any frame's window tree is always a binary tree.

Obviously I'd prefer to say something more useful like "for all frames
invariantly holds that if this variable is non-nil when that frame is
created or a window on that frame is created or deleted, that frame's
window tree is a binary tree" but I don't like talking in terms of pre-
and post-conditions and don't know anyway how to provide the necessary
atomicity of Emacs' actions wrt to "this variable's value".

 > Perhaps framing this in terms of a guarantee is clearer?
 >
 >> If this variable's value remains non-`nil' throughout the lifetime of
 >> a frame, the frame's window tree is guaranteed to be a binary tree;
 >> every window nested below the root window will have exactly one
 >> sibling.

I wouldn't mind.  After all, this sentence was meant as an additional
hint only, without the slightest claim for formal correctness.

martin

Re: Windows' "split status"

[Eli Zaretskii]

> Date: Wed, 23 Nov 2011 15:15:19 +0100
> From: martin rudalics <rudalics@gmx.at>
> Cc: Chong Yidong <cyd@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>,
> 	emacs-devel@gnu.org
> 
> The term "always" has very contrived semantics

Try "at all times" instead.

Re: Windows' "split status"

[martin rudalics]

 >> The term "always" has very contrived semantics
 >
 > Try "at all times" instead.

"always" means for me "in the initial state and in all states reachable
from the initial state" where transitions between states are considerd
atomic.  I don't know what "times" in "at all times" refers to: Real
time, time measured by the system clock?  How avoid that these get me an
intermediate state where a consequent doesn't hold?

martin

Re: Windows' "split status"

[Eli Zaretskii]

> Date: Wed, 23 Nov 2011 20:21:30 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: nix@esperi.org.uk, cyd@gnu.org, monnier@iro.umontreal.ca, 
>  emacs-devel@gnu.org
> 
> I don't know what "times" in "at all times" refers to: Real time,
> time measured by the system clock?

Google will tell.  E.g., this:

   http://idioms.yourdictionary.com/at-all-times

Re: Windows' "split status"

[martin rudalics]

 >    http://idioms.yourdictionary.com/at-all-times

Both http://www.merriam-webster.com/dictionary/always and
http://www.thefreedictionary.com/always give for "always" the
definition "at all times".

martin

Re: Windows' "split status"

[Eli Zaretskii]

> Date: Thu, 24 Nov 2011 11:00:04 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: nix@esperi.org.uk, cyd@gnu.org, monnier@iro.umontreal.ca, 
>  emacs-devel@gnu.org
> 
>  >    http://idioms.yourdictionary.com/at-all-times
> 
> Both http://www.merriam-webster.com/dictionary/always and
> http://www.thefreedictionary.com/always give for "always" the
> definition "at all times".

Of course.  But it was you who said that "always" is ambiguous, so I
suggested a synonym that isn't.

Re: Windows' "split status"

[martin rudalics]

 > Of course.  But it was you who said that "always" is ambiguous, so I
 > suggested a synonym that isn't.

"always" is ambiguous because within executing `split-window-internal'
or `delete-window-internal' the property doesn't necessarily hold.
Hence, for a strict interpretation of the word "always" my claim is not
valid.  I don't see how using "at all times" could remedy this.

martin

Re: Windows' "split status"

[Eli Zaretskii]

> Date: Fri, 25 Nov 2011 11:24:41 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: nix@esperi.org.uk, cyd@gnu.org, monnier@iro.umontreal.ca, 
>  emacs-devel@gnu.org
> 
> I don't see how using "at all times" could remedy this.

I do, but feel free to ignore my suggestion if you don't like it.

Re: Windows' "split status"

[Nix]

On 25 Nov 2011, martin rudalics outgrape:

>> Of course.  But it was you who said that "always" is ambiguous, so I
>> suggested a synonym that isn't.
>
> "always" is ambiguous because within executing `split-window-internal'
> or `delete-window-internal' the property doesn't necessarily hold.

Uh, why on earth would a user reading a docstring care about that? The
insides of Emacs's implementation are of no interest to her. Lots of
Emacs invariants don't hold while various built-in functions are
executing (in fact, no invariant relying on more state than a single
atomic variable can hold at all times). That doesn't mean they're any
less invariants at the Lisp level. (For that matter, there are
invariants that hold at the user level which do not hold at the Lisp
level: they too are still invariants from the user's perspective, even
if not from the Lisp programmer's.)

I thought this was documentation for Lisp developers, not for Emacs
maintainers. If it's for Emacs maintainers it's probably in the wrong
place (though having such documentation is praiseworthy).

-- 
NULL && (void)

Re: Windows' "split status"

[Eli Zaretskii]

> From: Nix <nix@esperi.org.uk>
> Emacs: resistance is futile; you will be assimilated and byte-compiled.
> Date: Fri, 25 Nov 2011 12:00:30 +0000
> Cc: Eli Zaretskii <eliz@gnu.org>, cyd@gnu.org, monnier@iro.umontreal.ca,
> 	emacs-devel@gnu.org
> 
> I thought this was documentation for Lisp developers, not for Emacs
> maintainers.

It's both, actually.  There's no other place to look for documentation
of Emacs internals except the ELisp manuals, because the comments
never tell enough.  When you want to change some complex piece of
code, and look for a comprehensive documentation of its contract, the
ELisp manual is the only place you can find something close.

But I don't think this invalidates your point.

Re: Windows' "split status"

[Nix]

On 25 Nov 2011, Eli Zaretskii verbalised:

>> From: Nix <nix@esperi.org.uk>
>> Emacs: resistance is futile; you will be assimilated and byte-compiled.
>> Date: Fri, 25 Nov 2011 12:00:30 +0000
>> Cc: Eli Zaretskii <eliz@gnu.org>, cyd@gnu.org, monnier@iro.umontreal.ca,
>> 	emacs-devel@gnu.org
>> 
>> I thought this was documentation for Lisp developers, not for Emacs
>> maintainers.
>
> It's both, actually.  There's no other place to look for documentation
> of Emacs internals except the ELisp manuals, because the comments
> never tell enough.  When you want to change some complex piece of
> code, and look for a comprehensive documentation of its contract, the
> ELisp manual is the only place you can find something close.

Yes indeed. I'm not saying it's not *useful* for Emacs maintainers!

> But I don't think this invalidates your point.

Quite. Lots of docstrings talk about invariants, because this is really
useful. Even something like the description of what `right-char' or
`newline' do are invariants. None of them should eschew talking about
those invariants simply because they are not atomic from the POV of the
Emacs core. Heck, `newline' is written in Lisp: from the POV of the
Emacs core, `newline' inserts soft newlines and then later marks them
hard, but nonetheless we talk about `newline' always inserting hard
newlines.


Where this suddenly does become urgent is if we ever find a way to
multithread Emacs -- but I strongly suspect that an Emacs with locking
fine-grained enough to maintain useful invariants would be
unmaintainable, as would an Emacs in which none of those invariants were
maintained cross-thread. What we'll need for multithreading is some sort
of transactional-memory scheme where Lisp in separate threads sees no
change to the state of Emacs from other threads until it (exits|returns
to the command loop|executes some special thread-yield function), and
even then the only changes it should see are those that have been done
in other threads that have reached the same point.

-- 
NULL && (void)

Re: Windows' "split status"

[martin rudalics]

 > Uh, why on earth would a user reading a docstring care about that? The
 > insides of Emacs's implementation are of no interest to her. Lots of
 > Emacs invariants don't hold while various built-in functions are
 > executing (in fact, no invariant relying on more state than a single
 > atomic variable can hold at all times). That doesn't mean they're any
 > less invariants at the Lisp level.

Then why do you complain about the use of "always" in the first place?
"always" (aka "globally") is the basic operator of temporal logic for
proving that a property is an invariant.

martin

Re: Windows' "split status"

[martin rudalics]

> I do, but feel free to ignore my suggestion if you don't like it.

If you do I'll use it.

martin

Re: Windows' "split status"

[martin rudalics]

 > Quite. Lots of docstrings talk about invariants, because this is really
 > useful. Even something like the description of what `right-char' or
 > `newline' do are invariants.

An invariant is a property (or a formula) that is valid when Emacs starts
and is preserved by every atomic step in any execution of Emacs.  The
description of what a function does is not an invariant (unless you mean
that the execution of Emacs leaves the description itself alone).

 > None of them should eschew talking about
 > those invariants simply because they are not atomic

What is an atomic invariant?

 > from the POV of the Emacs core.

martin

Re: Windows' "split status"

[martin rudalics]

 >>> But I think this result is just a consequence of the implementation
 >>> rather than actual intention.  My impression is that window-nest is
 >>> trying to solve a problem which can't be solved with a user-config: it's
 >>> trying to provide some kind of way for elisp packages to use parent
 >>> windows as a form of "very lightweight sub-frame", without touching much
 >>> of their code (e.g. without making their code use parent windows
 >>> explicitly).
 >>> IIUC the use of window-nest for that purpose only works if the
 >>> application limits itself to using 2 windows within that "sub-frame",
 >
 >> What makes you think that?
 >
 > Are you saying that my description of the intention behind window-nest
 > is wrong?  Or are you only saying that the "at most 2" limitation is not
 > really true. while everything else is right?

When using side windows there must be exactly one major non-side window
containing all other non-side windows.  That window can be considered a
"very lightweight sub-frame".  But the number of subwindows of that
window is not limited in any sense.

 > I don't actually know what was the intention behind window-nest, so
 > confirmation would be welcome.

Your characterization above is OK.  Just that there's no limitation.

 >> You can let-bind `window-nest' to t around a
 >> split and get an extra parent around the resulting two windows.  After
 >> that you can split those windows any which way you want and can get an
 >> arbitrary number of windows within a "sub-frame".  The manual explicitly
 >> uses the term "always" in the sentence
 >
 > That sounds like a rather round-about way to do things (because you have
 > let-bind the var around some parts of he code, but not all): wouldn't it
 > be easier to start with "create a parent window" (which would start
 > containing only the selected window) an then proceed to split it the
 > usual way.  That would save you from using let-binding.

There are two problems with this:

(1) I invariantly disallow matryoshka windows, so each internal window
     must have at least two children.  Lifting this invariant might have
     tricky consequences.

(2) When deleting a window makes a parent recombinable with its
     siblings, I must be able to suppress that recombination - otherwise
     the "sub-frame" mechanism will break.

 >> `window-nest' is aimed at providing a safe low-level mechanism to
 >> construct and preserve parent windows.  Everything else can be easily
 >> built in Elisp on top of that, like atomic or side windows.
 >
 > If it's a low-level mechanism, why is it a defcustom, then?

It's a defcustom because earlier it was just a special value of a
precursor of an option now called `window-combination-resize'.  If you
think it's a bad idea, I can always turn it into a plain variable like
`display-buffer-mark-dedicated'.  OTOH, having it always non-nil makes
the behavior of window deletions more predictable as explained in the
manual.

 > If it's aimed at "construct and preserve", why is it a variable, rather
 > than a function?

It's a variable _and_ a slot in the window structure and it's used like
`display-buffer-mark-dedicated': Usually for one single call but there's
no harm if someone wants all windows be dedicated or all parent windows
have only two children.

martin