Understanding atomic window groups

Understanding atomic window groups

[Eric Abrahamsen]

[-- Attachment #1: Type: text/plain, Size: 1063 bytes --]

I'm playing around with adding atomic window support to Gnus, so that
help/completion/other-pop-up buffers don't end up squished between the
*Summary* and *Article* windows, but instead shift the whole window
composition over temporarily.

All of Gnus' window configuration goes through one function,
`gnus-configure-windows', so it's relatively easy to target. The patch
below seems to do the trick.

My question is about quitting/removing atomic window compositions. Gnus
switches through many different compositions, so it's necessary to be
able to quit atomic windows. As you can see in the diff, I've had to
manually, and recursively, remove the 'window-atom parameter before
reconfiguring windows.

Is that the way it's supposed to work? I guess I would have thought
there would be an easier way of getting rid of an atomic
configuration -- like `quit-window' in any of the windows would quit all
of them, or something like that. Instead, `quit-window' seems to just
signal an error.

Is this how it's supposed to work? Should I be doing this differently?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gnus-atomic-windows.diff --]
[-- Type: text/x-patch, Size: 1819 bytes --]

commit 80e9ac12529016a69926dfdc0b1ff6cf619a0751
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Date:   Sun Apr 21 11:04:20 2019 -0700

    WIP on making Gnus windows atomic

diff --git a/lisp/gnus/gnus-win.el b/lisp/gnus/gnus-win.el
index 5f7154c545..d30c8b84ad 100644
--- a/lisp/gnus/gnus-win.el
+++ b/lisp/gnus/gnus-win.el
@@ -38,6 +38,10 @@ gnus-use-full-window
   :group 'gnus-windows
   :type 'boolean)
 
+(defcustom gnus-use-atomic-windows t
+  "If non-nil, Gnus' window compositions will be atomic."
+  :type 'boolean)
+
 (defcustom gnus-window-min-width 2
   "Minimum width of Gnus buffers."
   :group 'gnus-windows
@@ -401,6 +405,15 @@ gnus-configure-windows
         (unless (gnus-buffer-live-p nntp-server-buffer)
           (nnheader-init-server-buffer))
 
+	;; Remove all 'window-atom parameters, as we're going to blast
+	;; and recreate the window layout.
+	(when-let ((parent (window-parent (selected-window))))
+	  (when (window-parameter parent 'window-atom)
+	    (walk-window-subtree
+	     (lambda (win)
+	       (set-window-parameter win 'window-atom nil))
+	     parent t)))
+
         ;; Either remove all windows or just remove all Gnus windows.
         (let ((frame (selected-frame)))
           (unwind-protect
@@ -422,6 +435,13 @@ gnus-configure-windows
           (set-buffer nntp-server-buffer)
           (gnus-configure-frame split)
           (run-hooks 'gnus-configure-windows-hook)
+
+	  ;; If we're using atomic windows, and the current frame has
+	  ;; multiple windows, make them atomic.
+	  (when (and gnus-use-atomic-windows
+		     (window-parent (selected-window)))
+	    (window-make-atom (window-parent (selected-window))))
+
           (when gnus-window-frame-focus
             (select-frame-set-input-focus
              (window-frame gnus-window-frame-focus)))))))))

Re: Understanding atomic window groups

[martin rudalics]

 > Is that the way it's supposed to work?

+	(when-let ((parent (window-parent (selected-window))))
+	  (when (window-parameter parent 'window-atom)

I don't know the precise semantics of 'when-let' but I think you
should use

(when (window-parameter nil 'window-atom)
   (let ((root (window-atom-root)))

and then 'walk-window-subtree' from root.  Otherwise, that's the way
to dissolve an atomic group of windows.

 > I guess I would have thought
 > there would be an easier way of getting rid of an atomic
 > configuration -- like `quit-window' in any of the windows would quit all
 > of them, or something like that. Instead, `quit-window' seems to just
 > signal an error.

'quit-window' does not necessarily restore to a state that invalidates
the atomicity of the containing group.  'delete-window' OTOH may do
that, so if 'quit-window' deletes all windows of an atomic group but
one, that atomic group is dissolved automatically.

martin

Re: Understanding atomic window groups

[Eric Abrahamsen]

On 05/23/19 10:39 AM, martin rudalics wrote:
>> Is that the way it's supposed to work?
>
> +	(when-let ((parent (window-parent (selected-window))))
> +	  (when (window-parameter parent 'window-atom)
>
> I don't know the precise semantics of 'when-let' but I think you
> should use
>
> (when (window-parameter nil 'window-atom)
>   (let ((root (window-atom-root)))
>
> and then 'walk-window-subtree' from root.  Otherwise, that's the way
> to dissolve an atomic group of windows.

Oh I see, thanks. I thought I had to check for the 'window-atom
parameter on the parent, if there was a parent.

>> I guess I would have thought
>> there would be an easier way of getting rid of an atomic
>> configuration -- like `quit-window' in any of the windows would quit all
>> of them, or something like that. Instead, `quit-window' seems to just
>> signal an error.
>
> 'quit-window' does not necessarily restore to a state that invalidates
> the atomicity of the containing group.  'delete-window' OTOH may do
> that, so if 'quit-window' deletes all windows of an atomic group but
> one, that atomic group is dissolved automatically.

Hmm, maybe it was `delete-window' that raised the error:

delete-window: Root of atomic window is root window of its frame

Whereas `quit-window' behaves in a way I can't quite pin down -- it
killed the buffer in one case but not in another, didn't change the
actual window layout, and moved point to the "first" of the atomic
windows.

Anyway, I'm not going to worry about it -- manually removing the
'window-atom parameter works fine, and any other solution would likely
involve deeper changes to Gnus' windowing than I want to fool with. This
setup is clean, anyway.

Thanks,
Eric

Re: Understanding atomic window groups

[martin rudalics]

 > Oh I see, thanks. I thought I had to check for the 'window-atom
 > parameter on the parent, if there was a parent.

Atomic windows can be arbitrarily nested so checking for atomicity of
the parent alone is in general not sufficient.

 >> 'quit-window' does not necessarily restore to a state that invalidates
 >> the atomicity of the containing group.  'delete-window' OTOH may do
 >> that, so if 'quit-window' deletes all windows of an atomic group but
 >> one, that atomic group is dissolved automatically.
 >
 > Hmm, maybe it was `delete-window' that raised the error:
 >
 > delete-window: Root of atomic window is root window of its frame
 >
 > Whereas `quit-window' behaves in a way I can't quite pin down -- it
 > killed the buffer in one case but not in another, didn't change the
 > actual window layout, and moved point to the "first" of the atomic
 > windows.

'quit-window' calls 'window-deletable-p' before it tries to delete a
window so it should never cause a "Root of atomic window is root
window of its frame" error.  If it does cause an error we have a bug
so maybe check again.

'delete-window' OTOH will raise an error when the root of the atomic
window is the root of the frame.  If you want to avoid that, typically
because most of your users who type C-x 0 expect the selected window
to disppear or those typing C-x 1 expect the selected window to become
the single window of its frame despite of atomicity, you will have to
adjust the behavior with the help of 'delete-window' and
'delete-other-windows' parameters for all involved windows.

martin

Re: Understanding atomic window groups

[Eli Zaretskii]

> From: martin rudalics <rudalics@gmx.at>
> Date: Fri, 24 May 2019 10:01:08 +0200
> Cc: emacs-devel@gnu.org
> 
> 'quit-window' calls 'window-deletable-p' before it tries to delete a
> window so it should never cause a "Root of atomic window is root
> window of its frame" error.  If it does cause an error we have a bug
> so maybe check again.
> 
> 'delete-window' OTOH will raise an error when the root of the atomic
> window is the root of the frame.

I think these factoids should be spelled out in the ELisp manual, and
perhaps also in the doc strings.

Re: Understanding atomic window groups

[Eric Abrahamsen]

martin rudalics <rudalics@gmx.at> writes:

>> Oh I see, thanks. I thought I had to check for the 'window-atom
>> parameter on the parent, if there was a parent.
>
> Atomic windows can be arbitrarily nested so checking for atomicity of
> the parent alone is in general not sufficient.

That's nuts! In a good way. Thanks for the information.

>>> 'quit-window' does not necessarily restore to a state that invalidates
>>> the atomicity of the containing group.  'delete-window' OTOH may do
>>> that, so if 'quit-window' deletes all windows of an atomic group but
>>> one, that atomic group is dissolved automatically.
>>
>> Hmm, maybe it was `delete-window' that raised the error:
>>
>> delete-window: Root of atomic window is root window of its frame
>>
>> Whereas `quit-window' behaves in a way I can't quite pin down -- it
>> killed the buffer in one case but not in another, didn't change the
>> actual window layout, and moved point to the "first" of the atomic
>> windows.
>
> 'quit-window' calls 'window-deletable-p' before it tries to delete a
> window so it should never cause a "Root of atomic window is root
> window of its frame" error.  If it does cause an error we have a bug
> so maybe check again.

No, it was `delete-window' that raised the error, as you describe below.
`quit-window' just behaved unpredictably.

> 'delete-window' OTOH will raise an error when the root of the atomic
> window is the root of the frame.  If you want to avoid that, typically
> because most of your users who type C-x 0 expect the selected window
> to disppear or those typing C-x 1 expect the selected window to become
> the single window of its frame despite of atomicity, you will have to
> adjust the behavior with the help of 'delete-window' and
> 'delete-other-windows' parameters for all involved windows.

This is really helpful, and I see that the docstring of `delete-window'
actually mentions the case of atomic windows. I agree with Eli that
maybe more documentation is in order. I feel like all the pieces are
present (here and there), but there's no one place to get a full
overview.

Thanks,
Eric

Re: Understanding atomic window groups

[martin rudalics]

 > `quit-window' just behaved unpredictably.

The idea behind `quit-window' is that it should _never_ bark at the
user but silently use the next-best solution when the predefined one
fails.  For example, typing C-h m usually displays a new *Help*
window.  Typing 'q' in that window conceptually deletes that window
because it did not exist before showing *Help*.  But if you do C-x 1
in the *Help* window first and then type 'q', that window can't be
deleted and thus will have to show some other buffer instead.

 > This is really helpful, and I see that the docstring of `delete-window'
 > actually mentions the case of atomic windows. I agree with Eli that
 > maybe more documentation is in order. I feel like all the pieces are
 > present (here and there), but there's no one place to get a full
 > overview.

The "one place" should be section 28.18 of the Elisp manual.  If
something is missing there, please complain right away.  I'll now try
to amend the manual entries for 'split-window', 'delete-window' and
'delete-other-windows' appropriately as Eli suggested.  There I'll
then have to talk about side windows as well so this may take some
time.

And if you want a function like the below please tell me.

Thanks, martin


(defun window-dissolve-atom (&optional window)
   "Dissolve atomic window WINDOW is part of.
WINDOW must be a valid window and defaults to the selected one."
   (setq window (window-normalize-window window))
   (when (window-parameter window 'window-atom)
     (let ((root (window-atom-root window)))
       (walk-window-subtree
        (lambda (window)
	 (when (window-parameter window 'window-atom)
	   (set-window-parameter window 'window-atom nil)))
        root t))))

Re: Understanding atomic window groups

[Eli Zaretskii]

> From: martin rudalics <rudalics@gmx.at>
> Date: Sat, 25 May 2019 09:59:03 +0200
> 
>  > This is really helpful, and I see that the docstring of `delete-window'
>  > actually mentions the case of atomic windows. I agree with Eli that
>  > maybe more documentation is in order. I feel like all the pieces are
>  > present (here and there), but there's no one place to get a full
>  > overview.
> 
> The "one place" should be section 28.18 of the Elisp manual.  If
> something is missing there, please complain right away.

AFAICT, that section lists the functions affected by atomic windows,
but doesn't tell what you said earlier:

> 'quit-window' calls 'window-deletable-p' before it tries to delete a
> window so it should never cause a "Root of atomic window is root
> window of its frame" error.  If it does cause an error we have a bug
> so maybe check again.
> 
> 'delete-window' OTOH will raise an error when the root of the atomic
> window is the root of the frame.  If you want to avoid that, typically
> because most of your users who type C-x 0 expect the selected window
> to disppear or those typing C-x 1 expect the selected window to become
> the single window of its frame despite of atomicity, you will have to
> adjust the behavior with the help of 'delete-window' and
> 'delete-other-windows' parameters for all involved windows.

> I'll now try to amend the manual entries for 'split-window',
> 'delete-window' and 'delete-other-windows' appropriately as Eli
> suggested.

It's up to you whether to describe the behavior with atomic windows
where the functions are described or where the atomic windows are
described.  In the latter case, the description of the functions
should have a cross-reference to the atomic-windows section.

Thanks.

Re: Understanding atomic window groups

[martin rudalics]

 > AFAICT, that section lists the functions affected by atomic windows,
 > but doesn't tell what you said earlier:
 >
 >> 'quit-window' calls 'window-deletable-p' before it tries to delete a
 >> window so it should never cause a "Root of atomic window is root
 >> window of its frame" error.  If it does cause an error we have a bug
 >> so maybe check again.
 >>
 >> 'delete-window' OTOH will raise an error when the root of the atomic
 >> window is the root of the frame.  If you want to avoid that, typically
 >> because most of your users who type C-x 0 expect the selected window
 >> to disppear or those typing C-x 1 expect the selected window to become
 >> the single window of its frame despite of atomicity, you will have to
 >> adjust the behavior with the help of 'delete-window' and
 >> 'delete-other-windows' parameters for all involved windows.

I tried to add the according information now.  If I should say more,
please tell me.

 > It's up to you whether to describe the behavior with atomic windows
 > where the functions are described or where the atomic windows are
 > described.  In the latter case, the description of the functions
 > should have a cross-reference to the atomic-windows section.

Cross references should be there now.

martin

Re: Understanding atomic window groups

[Eli Zaretskii]

> Cc: eric@ericabrahamsen.net, emacs-devel@gnu.org
> From: martin rudalics <rudalics@gmx.at>
> Date: Mon, 3 Jun 2019 11:11:29 +0200
> 
>  > AFAICT, that section lists the functions affected by atomic windows,
>  > but doesn't tell what you said earlier:
>  >
>  >> 'quit-window' calls 'window-deletable-p' before it tries to delete a
>  >> window so it should never cause a "Root of atomic window is root
>  >> window of its frame" error.  If it does cause an error we have a bug
>  >> so maybe check again.
>  >>
>  >> 'delete-window' OTOH will raise an error when the root of the atomic
>  >> window is the root of the frame.  If you want to avoid that, typically
>  >> because most of your users who type C-x 0 expect the selected window
>  >> to disppear or those typing C-x 1 expect the selected window to become
>  >> the single window of its frame despite of atomicity, you will have to
>  >> adjust the behavior with the help of 'delete-window' and
>  >> 'delete-other-windows' parameters for all involved windows.
> 
> I tried to add the according information now.  If I should say more,
> please tell me.

LGTM, thanks.

Re: Understanding atomic window groups

[Eric Abrahamsen]

martin rudalics <rudalics@gmx.at> writes:

>> `quit-window' just behaved unpredictably.
>
> The idea behind `quit-window' is that it should _never_ bark at the
> user but silently use the next-best solution when the predefined one
> fails.  For example, typing C-h m usually displays a new *Help*
> window.  Typing 'q' in that window conceptually deletes that window
> because it did not exist before showing *Help*.  But if you do C-x 1
> in the *Help* window first and then type 'q', that window can't be
> deleted and thus will have to show some other buffer instead.

Okay, I do see that `quit-window' has a more complicated job to do, and
multiple conditions are checked. I guess I was hoping/expecting that
`quit-window' in a member of an atomic window group could somehow be
altered to act on the whole group, rather than just the current window.

>> This is really helpful, and I see that the docstring of `delete-window'
>> actually mentions the case of atomic windows. I agree with Eli that
>> maybe more documentation is in order. I feel like all the pieces are
>> present (here and there), but there's no one place to get a full
>> overview.
>
> The "one place" should be section 28.18 of the Elisp manual.  If
> something is missing there, please complain right away.  I'll now try
> to amend the manual entries for 'split-window', 'delete-window' and
> 'delete-other-windows' appropriately as Eli suggested.  There I'll
> then have to talk about side windows as well so this may take some
> time.

I would at least add the fact that atomic groups can be nested, and say
something about how to get _rid_ of an atomic group. When I was first
experimenting, I ended up having to reboot emacs, because I couldn't
figure out how to un-atomic the frame.

It would be great to have more examples in the side windows section as
well. The two features together feel like they could be very powerful,
there's just a bit of a documentation gap.

I've had it in the back of my mind to try replacing Gnus' homemade
windowing functionality with side windows, because they do pretty much
the same thing, but I'm not sure where to start. In particular, the doc
examples show a setup where certain buffers appear to _always_ be
displayed in certain side buffers. My assumption is that in the vast
majority of cases, people would want to display _this_ particular group
of buffers in a certain way on _this_ frame, and not pollute the global
config.

> And if you want a function like the below please tell me.

Now that I've seen it, I don't need you to add it :)

Generally, the code I've ended up writing for windowing stuff has always
been pretty simple, once I figure it out. But some more help figuring it
out would be very welcome.

Thanks,
Eric

Re: Understanding atomic window groups

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> martin rudalics <rudalics@gmx.at> writes:
>
>>> `quit-window' just behaved unpredictably.
>>
>> The idea behind `quit-window' is that it should _never_ bark at the
>> user but silently use the next-best solution when the predefined one
>> fails.  For example, typing C-h m usually displays a new *Help*
>> window.  Typing 'q' in that window conceptually deletes that window
>> because it did not exist before showing *Help*.  But if you do C-x 1
>> in the *Help* window first and then type 'q', that window can't be
>> deleted and thus will have to show some other buffer instead.
>
> Okay, I do see that `quit-window' has a more complicated job to do, and
> multiple conditions are checked. I guess I was hoping/expecting that
> `quit-window' in a member of an atomic window group could somehow be
> altered to act on the whole group, rather than just the current window.

For instance! Side windows have `window-toggle-side-windows', maybe we
could have something similar for atomic windows?

[...]

> It would be great to have more examples in the side windows section as
> well. The two features together feel like they could be very powerful,
> there's just a bit of a documentation gap.
>
> I've had it in the back of my mind to try replacing Gnus' homemade
> windowing functionality with side windows, because they do pretty much
> the same thing, but I'm not sure where to start.

Just to extend this hypothetical:

Gnus configures its various window layouts in
`gnus-buffer-configuration', an assoc list where each element looks
like:

(article
  (horizontal 1.0
    (vertical 0.5
      (group 1.0))
    (vertical 1.0
      (summary 0.25 point)
      (article 1.0))))

This configuration is selected using 'article as a key --
(gnus-configure-windows 'article) -- the rest of it is arbitrarily
nested instructions about how to split the various buffer and how big
the splits should be.

As a lazy developer, I'd like to be able to pull apart the setting
above, find the window with 'point and make that the "main window", and
use the rest of the information to issue a series of (probably)
`display-buffer-in-side-window' calls that put the rest of the windows
in place. It would be particularly nice if we could stick an 'atomic key
in the above setting, and have the resulting side window assembly be
atomic.

Maybe this is totally possible right now, I don't know.

Eric

Re: Understanding atomic window groups

[martin rudalics]

 > For instance! Side windows have `window-toggle-side-windows', maybe we
 > could have something similar for atomic windows?

'window-toggle-side-windows' was a specific wish of people of the
people who wanted an IDE-like environment.  As for atomic windows do
you mean something like "make an atomic window occupy the main window
of its frame" and restore the remaining windows when toggling again?

 >> I've had it in the back of my mind to try replacing Gnus' homemade
 >> windowing functionality with side windows, because they do pretty much
 >> the same thing, but I'm not sure where to start.
 >
 > Just to extend this hypothetical:
 >
 > Gnus configures its various window layouts in
 > `gnus-buffer-configuration', an assoc list where each element looks
 > like:
 >
 > (article
 >    (horizontal 1.0
 >      (vertical 0.5
 >        (group 1.0))
 >      (vertical 1.0
 >        (summary 0.25 point)
 >        (article 1.0))))
 >
 > This configuration is selected using 'article as a key --
 > (gnus-configure-windows 'article) -- the rest of it is arbitrarily
 > nested instructions about how to split the various buffer and how big
 > the splits should be.

I'd need more information of the type what kind of windows you want to
show and how they should be laid out on a frame.  The basic idea of
side windows was that there are main windows where the user is editing
and side windows where additional information is shown.  How would
that relate to gnus?

 > As a lazy developer, I'd like to be able to pull apart the setting
 > above, find the window with 'point and make that the "main window", and
 > use the rest of the information to issue a series of (probably)
 > `display-buffer-in-side-window' calls that put the rest of the windows
 > in place. It would be particularly nice if we could stick an 'atomic key
 > in the above setting, and have the resulting side window assembly be
 > atomic.

Again I would have to know the character of the "rest of the windows".
Are they meant for editing?

martin

Re: Understanding atomic window groups

[martin rudalics]

 > Okay, I do see that `quit-window' has a more complicated job to do, and
 > multiple conditions are checked. I guess I was hoping/expecting that
 > `quit-window' in a member of an atomic window group could somehow be
 > altered to act on the whole group, rather than just the current window.

We would have to specify the respective semantics first.  Atomic
groups by default do not have main windows.  All its constituting live
windows are treated equal - as, for example, two side-by-side windows
showing the diffs of a file.  If we want to designate one constituent
of an atomic window as the "main" window and have 'quit-window' act on
the entire group as the 'quit-restore' parameter of that main window
says, we would have to write specific code for 'quit-restore-window'.

 > I would at least add the fact that atomic groups can be nested,

When I first used the term "nested" I only meant that an atomic window
can comprise an arbitrary number of windows as long as the resulting
window has a rectangular shape.  That's why I asked you to act on the
root of the atomic window instead on the parent of one of its
constituents.  I'm not sure what to say more about this in the manual
- maybe you can propose the necessary change.

 > and say
 > something about how to get _rid_ of an atomic group. When I was first
 > experimenting, I ended up having to reboot emacs, because I couldn't
 > figure out how to un-atomic the frame.

I tried to say that now.

 > It would be great to have more examples in the side windows section as
 > well. The two features together feel like they could be very powerful,
 > there's just a bit of a documentation gap.

I already devote an entire subsection to an example.

 > I've had it in the back of my mind to try replacing Gnus' homemade
 > windowing functionality with side windows, because they do pretty much
 > the same thing, but I'm not sure where to start. In particular, the doc
 > examples show a setup where certain buffers appear to _always_ be
 > displayed in certain side buffers. My assumption is that in the vast
 > majority of cases, people would want to display _this_ particular group
 > of buffers in a certain way on _this_ frame, and not pollute the global
 > config.

Which use case do you have in mind?  The people asking before for such
a feature wanted the layout apply to any frame - that is, side windows
should specify the global configuration.

martin

Re: Understanding atomic window groups

[Eric Abrahamsen]

On 06/03/19 11:12 AM, martin rudalics wrote:
>> Okay, I do see that `quit-window' has a more complicated job to do, and
>> multiple conditions are checked. I guess I was hoping/expecting that
>> `quit-window' in a member of an atomic window group could somehow be
>> altered to act on the whole group, rather than just the current window.
>
> We would have to specify the respective semantics first.  Atomic
> groups by default do not have main windows.  All its constituting live
> windows are treated equal - as, for example, two side-by-side windows
> showing the diffs of a file.  If we want to designate one constituent
> of an atomic window as the "main" window and have 'quit-window' act on
> the entire group as the 'quit-restore' parameter of that main window
> says, we would have to write specific code for 'quit-restore-window'.

No, that's probably not worth it.

>> I would at least add the fact that atomic groups can be nested,
>
> When I first used the term "nested" I only meant that an atomic window
> can comprise an arbitrary number of windows as long as the resulting
> window has a rectangular shape.  That's why I asked you to act on the
> root of the atomic window instead on the parent of one of its
> constituents.  I'm not sure what to say more about this in the manual
> - maybe you can propose the necessary change.

I was misunderstanding what you meant by "nested".

>> and say
>> something about how to get _rid_ of an atomic group. When I was first
>> experimenting, I ended up having to reboot emacs, because I couldn't
>> figure out how to un-atomic the frame.
>
> I tried to say that now.
>
>> It would be great to have more examples in the side windows section as
>> well. The two features together feel like they could be very powerful,
>> there's just a bit of a documentation gap.
>
> I already devote an entire subsection to an example.

The new docs look great, and clear up quite a few of my confusions,
thank you.

>> I've had it in the back of my mind to try replacing Gnus' homemade
>> windowing functionality with side windows, because they do pretty much
>> the same thing, but I'm not sure where to start. In particular, the doc
>> examples show a setup where certain buffers appear to _always_ be
>> displayed in certain side buffers. My assumption is that in the vast
>> majority of cases, people would want to display _this_ particular group
>> of buffers in a certain way on _this_ frame, and not pollute the global
>> config.
>
> Which use case do you have in mind?  The people asking before for such
> a feature wanted the layout apply to any frame - that is, side windows
> should specify the global configuration.

I'll answer this below.

On 06/03/19 11:13 AM, martin rudalics wrote:
>> For instance! Side windows have `window-toggle-side-windows', maybe we
>> could have something similar for atomic windows?
>
> 'window-toggle-side-windows' was a specific wish of people of the
> people who wanted an IDE-like environment.  As for atomic windows do
> you mean something like "make an atomic window occupy the main window
> of its frame" and restore the remaining windows when toggling again?

I was thinking the toggle would first remove the atomic property from a
group of windows and record the fact that they used to be atomic. The
next call would restore that atomicity. But... recording _how_ they were
arranged, and restoring them when the entire frame has possibly been
rearranged in the meantime, sounds onerous and weird.

Maybe the `window-dissolve-atom' function you posted above would be
enough. It's not terribly mysterious code, but it is a very useful
utility function, particularly for people who are just getting into
this.

>>> I've had it in the back of my mind to try replacing Gnus' homemade
>>> windowing functionality with side windows, because they do pretty much
>>> the same thing, but I'm not sure where to start.
>>
>> Just to extend this hypothetical:
>>
>> Gnus configures its various window layouts in
>> `gnus-buffer-configuration', an assoc list where each element looks
>> like:
>>
>> (article
>>    (horizontal 1.0
>>      (vertical 0.5
>>        (group 1.0))
>>      (vertical 1.0
>>        (summary 0.25 point)
>>        (article 1.0))))
>>
>> This configuration is selected using 'article as a key --
>> (gnus-configure-windows 'article) -- the rest of it is arbitrarily
>> nested instructions about how to split the various buffer and how big
>> the splits should be.
>
> I'd need more information of the type what kind of windows you want to
> show and how they should be laid out on a frame.  The basic idea of
> side windows was that there are main windows where the user is editing
> and side windows where additional information is shown.  How would
> that relate to gnus?

The typical example looks like:

+------------------------------+
|  Summary     		       |
|	  		       |
+-------------------+----------+-
|         	    |	       |
|  Article     	    |  BBDB    |
|		    |  	       |
|		    | 	       |
+-------------------+----------+

Where point is in the Summary window -- that's the "main" window. It's
possible to put point in the Article or BBDB windows and do things
there, but the Summary keymap contains all kinds of bindings for
operating on the other two windows "remotely".

Gnus has many buffers (see `gnus-window-to-buffer'), and many potential
window configurations (the manual lists 22 known possibilities). The
same buffers might be displayed in different locations in different
configurations, which is why the `display-buffer-alist' approach doesn't
seem to fit.

It's possible that (as is often the case) Gnus' mechanisms are too
idiosyncratic to be recreated with built-in tools. If so, that's totally
fine -- I just thought that, if it were possible, it would be a nice
refactor.

Thanks again for the docs!
Eric

Re: Understanding atomic window groups

[martin rudalics]

 > I was thinking the toggle would first remove the atomic property from a
 > group of windows and record the fact that they used to be atomic. The
 > next call would restore that atomicity. But... recording _how_ they were
 > arranged, and restoring them when the entire frame has possibly been
 > rearranged in the meantime, sounds onerous and weird.

I consider making and dissolving atomic windows rather specific to
Gnus and it should be probaly done there.  Only if there is a more
general need, such functionality should be provided by window.el.

 > Maybe the `window-dissolve-atom' function you posted above would be
 > enough. It's not terribly mysterious code, but it is a very useful
 > utility function, particularly for people who are just getting into
 > this.

I can add it any time.

 > The typical example looks like:
 >
 > +------------------------------+
 > |  Summary     		       |
 > |	  		       |
 > +-------------------+----------+-
 > |         	    |	       |
 > |  Article     	    |  BBDB    |
 > |		    |  	       |
 > |		    | 	       |
 > +-------------------+----------+
 >
 > Where point is in the Summary window -- that's the "main" window. It's
 > possible to put point in the Article or BBDB windows and do things
 > there, but the Summary keymap contains all kinds of bindings for
 > operating on the other two windows "remotely".

Is BBDB something typical for Gnus?  I thought the "group" window is
the more typical one.  Or maybe the ones for composing messages or
articles.

 > Gnus has many buffers (see `gnus-window-to-buffer'), and many potential
 > window configurations (the manual lists 22 known possibilities).

Where is all that documented?  'gnus-window-to-buffer', for example?
I suppose the 22 possibilities are the ones from section 9.5.1 of the
Gnus manual.  So probably I get some predefined hardcoded layout when
doing, say 'gnus-summary-edit-article' and when done with editing the
previous layout gets restored.  But where is that described?  And how
can I customize it?

Looking at section 9.5 Window Layout: It starts with saying that there
are glitches with 'gnus-use-full-window' (which should probably be
called 'gnus-use-full-frame').  But wouldn't embedding Gnus' windows
in an Emacs frame be one of the primary tasks of the layout mechanism?

Next it says that ‘gnus-buffer-configuration’ describes how much space
each Gnus buffer should be given.  IMO it should rather say how much
space a window like the "summary window" or "article window" are
given.  Below it even talks about "splitting buffers" ...

Also, a sentence like "In a ‘frame’ split, the last subsplit having a
leaf split where the tag ‘frame-focus’ is a member ..." is very hard
to comprehend - I failed.

 > The
 > same buffers might be displayed in different locations in different
 > configurations, which is why the `display-buffer-alist' approach doesn't
 > seem to fit.

I don't think that specifying layouts operationally via "vertical" and
"horizontal" splits is bad per se and people are most likely used to
it.  But I think that some descriptive layer maybe on top of the
operational one using terms like "top", "above" or "right" would be
more suitable for people using Gnus for the first time.  In either
case I failed to decipher the layout sketched in section 9.5.2 from
the two (why two?) accompanying 'gnus-add-configuration' calls.

 > It's possible that (as is often the case) Gnus' mechanisms are too
 > idiosyncratic to be recreated with built-in tools. If so, that's totally
 > fine -- I just thought that, if it were possible, it would be a nice
 > refactor.

I would like to see a comprehensible and more complete documentation
of Gnus' windows layouts first.  Then we could talk about an
alternative, less operational specification of the layout and how to
support it with the help of Emacs' core functions.

Thanks, martin

Re: Understanding atomic window groups

[Eric Abrahamsen]

martin rudalics <rudalics@gmx.at> writes:

>> I was thinking the toggle would first remove the atomic property from a
>> group of windows and record the fact that they used to be atomic. The
>> next call would restore that atomicity. But... recording _how_ they were
>> arranged, and restoring them when the entire frame has possibly been
>> rearranged in the meantime, sounds onerous and weird.
>
> I consider making and dissolving atomic windows rather specific to
> Gnus and it should be probaly done there.  Only if there is a more
> general need, such functionality should be provided by window.el.
>
>> Maybe the `window-dissolve-atom' function you posted above would be
>> enough. It's not terribly mysterious code, but it is a very useful
>> utility function, particularly for people who are just getting into
>> this.
>
> I can add it any time.

Sounds reasonable -- I'm the only one who's complained about this so
far, anyway. Let's leave it for now.

>> The typical example looks like:
>>
>> +------------------------------+
>> |  Summary     		       |
>> |	  		       |
>> +-------------------+----------+-
>> |         	    |	       |
>> |  Article     	    |  BBDB    |
>> |		    |  	       |
>> |		    | 	       |
>> +-------------------+----------+
>>
>> Where point is in the Summary window -- that's the "main" window. It's
>> possible to put point in the Article or BBDB windows and do things
>> there, but the Summary keymap contains all kinds of bindings for
>> operating on the other two windows "remotely".
>
> Is BBDB something typical for Gnus?  I thought the "group" window is
> the more typical one.  Or maybe the ones for composing messages or
> articles.

They're all typical! Just different layouts for different tasks. The
"group" layout is for browsing your groups and finding new mail, but
when you enter a group and select an article you often get something
like the above (the "article" layout). And yes, having BBDB visible is
very common, both in the "article" layout and the "message"
(composition) layout.

>> Gnus has many buffers (see `gnus-window-to-buffer'), and many potential
>> window configurations (the manual lists 22 known possibilities).
>
> Where is all that documented?  'gnus-window-to-buffer', for example?
> I suppose the 22 possibilities are the ones from section 9.5.1 of the
> Gnus manual.  So probably I get some predefined hardcoded layout when
> doing, say 'gnus-summary-edit-article' and when done with editing the
> previous layout gets restored.  But where is that described?  And how
> can I customize it?

All the layouts are stored in `gnus-buffer-configuration'. It comes with
defaults, and you can mangle it however you please. The layouts are
selected with `gnus-configure-frame'.

> Looking at section 9.5 Window Layout: It starts with saying that there
> are glitches with 'gnus-use-full-window' (which should probably be
> called 'gnus-use-full-frame').  But wouldn't embedding Gnus' windows
> in an Emacs frame be one of the primary tasks of the layout mechanism?

I think most people just let Gnus take up a whole frame.

> Next it says that ‘gnus-buffer-configuration’ describes how much space
> each Gnus buffer should be given. IMO it should rather say how much
> space a window like the "summary window" or "article window" are
> given.  Below it even talks about "splitting buffers" ...
>
> Also, a sentence like "In a ‘frame’ split, the last subsplit having a
> leaf split where the tag ‘frame-focus’ is a member ..." is very hard
> to comprehend - I failed.

Yup, the docs try pretty hard, but it's quite confusing. I'd be curious
to know how many people are actually using its more complex features,
like frame splits or putting in frame parameters instead of a simple
sizing float.

>> The
>> same buffers might be displayed in different locations in different
>> configurations, which is why the `display-buffer-alist' approach doesn't
>> seem to fit.
>
> I don't think that specifying layouts operationally via "vertical" and
> "horizontal" splits is bad per se and people are most likely used to
> it.  But I think that some descriptive layer maybe on top of the
> operational one using terms like "top", "above" or "right" would be
> more suitable for people using Gnus for the first time.  In either
> case I failed to decipher the layout sketched in section 9.5.2 from
> the two (why two?) accompanying 'gnus-add-configuration' calls.

`gnus-add-configuration' is just a convenience function for setting the
configuration of one "key" -- in that case the "summary" and "article"
keys. The ASCII art only depicts the first (article) layout, the summary
layout would be the same, but without the article window.

The configuration format is confusing to look at, but I do think it's
fine given the level of configurability the system is going for.

>> It's possible that (as is often the case) Gnus' mechanisms are too
>> idiosyncratic to be recreated with built-in tools. If so, that's totally
>> fine -- I just thought that, if it were possible, it would be a nice
>> refactor.
>
> I would like to see a comprehensible and more complete documentation
> of Gnus' windows layouts first.  Then we could talk about an
> alternative, less operational specification of the layout and how to
> support it with the help of Emacs' core functions.

I can probably take a whack at improving the docs. To be clear, though,
this is just an idea I had -- I haven't asked anyone if they actually
want this, or run it by Lars or anything. But if changes are
backwards-compatible, configuration-wise, and simply result in a net
removal of code, that should be fine. I'll try to get to the docs this
weekend.

Thanks,
Eric

Re: Understanding atomic window groups

[Eric Abrahamsen]

[-- Attachment #1: Type: text/plain, Size: 916 bytes --]

martin rudalics <rudalics@gmx.at> writes:


[...]

> I would like to see a comprehensible and more complete documentation
> of Gnus' windows layouts first. Then we could talk about an
> alternative, less operational specification of the layout and how to
> support it with the help of Emacs' core functions.

I've had a whack at updating the manual, and attached a diff. This is
obviously just a first try, and I imagine there will be much that needs
to be tweaked. To be honest, several of the examples in the manual
didn't work as advertised when I tried them, but I guess that's a
separate problem -- this is how it's _supposed_ to work, I think.

Two code notes:

- As you mentioned, `gnus-use-full-window' should be obsoleted in favor
  of `gnus-use-full-frame'.
- It would be nice if the size spec also accepted the symbol `fit',
  which would trigger a `fit-window-to-buffer'.

Hope this clarifies things...


[-- Attachment #2: gnus-window-docs.diff --]
[-- Type: text/x-patch, Size: 8640 bytes --]

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 11ee62d546..f15ec43f8b 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -22686,15 +22686,16 @@ Window Layout
 
 @vindex gnus-use-full-window
 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
-other windows and occupy the entire Emacs screen by itself.  It is
+other windows and occupy the entire Emacs frame by itself.  It is
 @code{t} by default.
 
 Setting this variable to @code{nil} kinda works, but there are
 glitches.  Use at your own peril.
 
 @vindex gnus-buffer-configuration
-@code{gnus-buffer-configuration} describes how much space each Gnus
-buffer should be given.  Here's an excerpt of this variable:
+@code{gnus-buffer-configuration} describes how to configure the
+windows that display Gnus buffers.  Here's an excerpt of this
+variable:
 
 @lisp
 ((group (vertical 1.0 (group 1.0 point)))
@@ -22707,28 +22708,35 @@ Window Layout
 configuration function will use @code{group} as the key.  A full list of
 possible names is listed below.
 
-The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer
-should occupy.  To take the @code{article} split as an example:
+The @dfn{value} (i.e., the @dfn{split}) says says which buffers to
+display, and how to arrange the windows they’re displayed in.  To take
+the @code{article} split as an example:
 
 @lisp
 (article (vertical 1.0 (summary 0.25 point)
                        (article 1.0)))
 @end lisp
 
-This @dfn{split} says that the summary buffer should occupy 25% of upper
-half of the screen, and that it is placed over the article buffer.  As
-you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
-reaching for that calculator there).  However, the special number
-@code{1.0} is used to signal that this buffer should soak up all the
-rest of the space available after the rest of the buffers have taken
-whatever they need.  There should be only one buffer with the @code{1.0}
-size spec per split.
+   This @dfn{split} starts with the symbol @code{vertical}, indicating
+that Gnus' window will be split into upper and lower windows.  Other
+common values are @code{horizontal}, resulting in a side-by-side
+split, or @code{frame}, which will create one or more new frames.  The
+@code{1.0} is a size specification indicating how much of the parent
+window, frame or split this split will occupy.  Following that is an
+arbitrary number of forms: either further splits, which can be nested
+as deeply as you like, or a specification for a buffer to display—in
+the example above, the summary and article buffers.
+
+This @dfn{split} says that the summary buffer should occupy the top
+25% of the frame, and the article buffer should occupy the bottom
+100%.  As you may have noticed, 100% + 25% is actually 125% (yup, I
+saw y’all reaching for that calculator there).  However, the special
+number @code{1.0} is used to signal that this buffer should soak up
+all the rest of the space available after the other buffers have taken
+whatever they need.
 
 Point will be put in the buffer that has the optional third element
-@code{point}.  In a @code{frame} split, the last subsplit having a leaf
-split where the tag @code{frame-focus} is a member (i.e., is the third or
-fourth element in the list, depending on whether the @code{point} tag is
-present) gets focus.
+@code{point}.
 
 Here's a more complicated example:
 
@@ -22750,26 +22758,25 @@ Window Layout
 Not complicated enough for you?  Well, try this on for size:
 
 @lisp
-(article (horizontal 1.0
-             (vertical 0.5
-                 (group 1.0))
-             (vertical 1.0
-                 (summary 0.25 point)
-                 (article 1.0))))
+(article (horizontal 1.0              -> Create side-by-side windows occupying the whole frame.
+             (vertical 0.5            -> The left window should occupy half the frame,
+                 (group 1.0))         -> and display nothing but the group buffer.
+             (vertical 1.0            -> The right window should occupy all remaining space.
+                 (summary 0.25 point) -> It's top quarter should display the summary and contain point,
+                 (article 1.0))))     -> and the remaining lower area display the article.
 @end lisp
 
-Whoops.  Two buffers with the mystery 100% tag.  And what's that
-@code{horizontal} thingie?
+Whoops.  Two buffers with the mystery 100% tag.
 
-If the first element in one of the split is @code{horizontal}, Gnus will
-split the window horizontally, giving you two windows side-by-side.
-Inside each of these strips you may carry on all you like in the normal
-fashion.  The number following @code{horizontal} says what percentage of
-the screen is to be given to this strip.
 
-For each split, there @emph{must} be one element that has the 100% tag.
-The splitting is never accurate, and this buffer will eat any leftover
-lines from the splits.
+At each level of split depth, there @emph{must} be one and only one
+element that has the 100% tag.  The splitting is never accurate, and
+this buffer will eat any leftover lines from the splits.  Also note
+that a split which contains only one member (in the example above, the
+first @code{vertical} split), can be specified as @code{vertical} or
+@code{horizontal}, it makes no difference as it is not actually split.
+FIXME: Actually that first vertical split seems redundant, it can be
+replaced with (group 0.5) directly, with the same effect.
 
 To be slightly more formal, here's a definition of what a valid split
 may look like:
@@ -22786,11 +22793,36 @@ Window Layout
 @end group
 @end example
 
-The limitations are that the @code{frame} split can only appear as the
-top-level split.  @var{form} should be an Emacs Lisp form that should
+@var{form} should be an Emacs Lisp form that should
 return a valid split.  We see that each split is fully recursive, and
 may contain any number of @code{vertical} and @code{horizontal} splits.
 
+Note that @code{frame} splits behave a little differently:
+
+@enumerate
+
+@item
+They can only appear as the top-level split, and can't be nested
+within other splits.
+
+@item
+The first sub-split of a frame split configures the already-existing
+frame---further subsplits will each create and configure a new frame.
+
+@item
+Each frame can have its own @code{point} tag; additionally one of the
+frames can have a @code{frame-focus} tag (either as the third element
+of a buffer spec, or the fourth if @code{point} is also present) which
+determines which frame has focus.
+
+@item
+Lastly, the size element of all newly-created frames (in other
+words, all but the first) should be an alist of frame parameters
+instead of the usual float or integer.  @xref{Frame Parameters, ,
+Frame Parameters, elisp, The GNU Emacs Lisp Reference Manual}
+
+@end enumerate
+
 @vindex gnus-window-min-width
 @vindex gnus-window-min-height
 @cindex window height
@@ -22849,16 +22881,10 @@ Window Layout
 @end lisp
 
 This split will result in the familiar summary/article window
-configuration in the first (or ``main'') frame, while a small additional
-frame will be created where picons will be shown.  As you can see,
-instead of the normal @code{1.0} top-level spec, each additional split
-should have a frame parameter alist as the size spec.
-@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
-Reference Manual}.  Under XEmacs, a frame property list will be
-accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)}
-is such a plist.
-The list of all possible keys for @code{gnus-buffer-configuration} can
-be found in its default value.
+configuration in the first (or ``main'') frame, while a small
+additional frame will be created where picons will be shown.  The list
+of all possible keys for @code{gnus-buffer-configuration} can be found
+in its default value.
 
 Note that the @code{message} key is used for both
 @code{gnus-group-mail} and @code{gnus-summary-mail-other-window}.  If
@@ -22908,9 +22934,9 @@ Window Layout
 Gnus has been loaded.
 
 @vindex gnus-always-force-window-configuration
-If all windows mentioned in the configuration are already visible, Gnus
-won't change the window configuration.  If you always want to force the
-``right'' window configuration, you can set
+If all buffers mentioned in the configuration are already visible,
+Gnus won't change the window configuration.  If you always want to
+force the ``right'' window configuration, you can set
 @code{gnus-always-force-window-configuration} to non-@code{nil}.
 
 If you're using tree displays (@pxref{Tree Display}), and the tree

Re: Understanding atomic window groups

[martin rudalics]

 > I've had a whack at updating the manual, and attached a diff. This is
 > obviously just a first try, and I imagine there will be much that needs
 > to be tweaked. To be honest, several of the examples in the manual
 > didn't work as advertised when I tried them, but I guess that's a
 > separate problem -- this is how it's _supposed_ to work, I think.

Thanks.

 > - As you mentioned, `gnus-use-full-window' should be obsoleted in favor
 >    of `gnus-use-full-frame'.

You should also specify _when_ things (liek the value of this
variable) take effect.  Note that with "window states" (Elisp manual
section 28.26) users should be able to save specific gnus layouts and
put them back into arbitrary windows, so maybe this variable is not so
important in the first place.

 > - It would be nice if the size spec also accepted the symbol `fit',
 >    which would trigger a `fit-window-to-buffer'.

'fit-window-to-buffer' might be hairy sometimes - triggered too often
it can be noisy and fitting adjacent windows can inherently cause
conflicts.  Maybe you also want some sort of fallback size when
fitting fails.


Some loose remarks on your changes and what they change:


'gnus-buffer-configuration' really means 'gnus-window-configuration'
although it's not a window configuration in the Emacs sense - maybe
'gnus-windows-layout' would be better.


The @dfn{key} is a symbol that names some action or
other.  For instance, when displaying the group buffer, the window
configuration function will use @code{group} as the key.  A full list of
possible names is listed below.

Why this restriction to "possible names"?  What if a user wants to
switch between two layouts both comprising the group buffer?  Below
you then say "the @code{message} key is used for both
@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}.  If
it is desirable to distinguish between the two, something like this
might be used" which IIUC means that the same symbol might name two
different layouts?  Is that a good idea?


"The @dfn{value} (i.e., the @dfn{split}) says says which buffers to"
has one "says" to many.  Also, since it's much more than a split I
would use a term like "layout" instead.  Below you also talk about
sub-splits/subsplits which somehow increase the confusion.


Point will be put in the buffer that has the optional third element
@code{point}.

"Point" is inappropriate here.  IIUC this just specifies the window to
select.


At each level of split depth, there @emph{must} be one and only one
element that has the 100% tag.

Is that restriction really needed?


If all buffers mentioned in the configuration are already visible,
Gnus won't change the window configuration.  If you always want to
force the ``right'' window configuration, you can set

Why is this useful and in which occasions does it apply?


Finally, it seems that there is no way to "save back" into
'gnus-buffer-configuration' a layout that has been obtained by
"manually" changing an existing layout.  Right?  Wouldn't that be
desirable?


martin

Re: Understanding atomic window groups

[Eric Abrahamsen]

martin rudalics <rudalics@gmx.at> writes:

>> I've had a whack at updating the manual, and attached a diff. This is
>> obviously just a first try, and I imagine there will be much that needs
>> to be tweaked. To be honest, several of the examples in the manual
>> didn't work as advertised when I tried them, but I guess that's a
>> separate problem -- this is how it's _supposed_ to work, I think.
>
> Thanks.
>
>> - As you mentioned, `gnus-use-full-window' should be obsoleted in favor
>>    of `gnus-use-full-frame'.
>
> You should also specify _when_ things (liek the value of this
> variable) take effect.  Note that with "window states" (Elisp manual
> section 28.26) users should be able to save specific gnus layouts and
> put them back into arbitrary windows, so maybe this variable is not so
> important in the first place.

I can mention that this only takes effect when `gnus-configure-windows'
is called. I'm not sure saving window state will be so useful: you might
say a particular layout describes the relationship of the group, summary
and article buffers, but the actual summary and article buffers will
change continuously.

>> - It would be nice if the size spec also accepted the symbol `fit',
>>    which would trigger a `fit-window-to-buffer'.
>
> 'fit-window-to-buffer' might be hairy sometimes - triggered too often
> it can be noisy and fitting adjacent windows can inherently cause
> conflicts.  Maybe you also want some sort of fallback size when
> fitting fails.

Okay. That can wait until later.

> Some loose remarks on your changes and what they change:
>
>
> 'gnus-buffer-configuration' really means 'gnus-window-configuration'
> although it's not a window configuration in the Emacs sense - maybe
> 'gnus-windows-layout' would be better.

Yup, that would probably be a better name.

> The @dfn{key} is a symbol that names some action or
> other.  For instance, when displaying the group buffer, the window
> configuration function will use @code{group} as the key.  A full list of
> possible names is listed below.
>
> Why this restriction to "possible names"?  What if a user wants to
> switch between two layouts both comprising the group buffer?  

In theory any key could be added to the alist, specifying any random
window layout, but nothing would ever call that code. A user could write
a function that calls `gnus-configure-windows' with their own symbol,
but if they know to do that, I doubt these docs would stop them.

> Below you then say "the @code{message} key is used for both
> @code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
> it is desirable to distinguish between the two, something like this
> might be used" which IIUC means that the same symbol might name two
> different layouts? Is that a good idea?

I don't know, tbh. The two possibilities describe the same state,
arrived at by different means. By that token you might want to
distinguish between "group layout after starting Gnus" from "group
layout after exiting a summary buffer". Maybe that would be desirable,
but I haven't thought much about it.

> "The @dfn{value} (i.e., the @dfn{split}) says says which buffers to"
> has one "says" to many. Also, since it's much more than a split I
> would use a term like "layout" instead.  Below you also talk about
> sub-splits/subsplits which somehow increase the confusion.

Oops, thanks for the catch. Yes, this should be more careful to
distinguish between a split (which might contain further splits) and a
layout (a top-level collection of splits).

> Point will be put in the buffer that has the optional third element
> @code{point}.
>
> "Point" is inappropriate here.  IIUC this just specifies the window to
> select.

Yup, we could change this to 'select (and look for both, for backward
compatibility).

> At each level of split depth, there @emph{must} be one and only one
> element that has the 100% tag.
>
> Is that restriction really needed?

I think it is, at least implicitly... The existing docs mention that
splitting by absolute line/column values might be imprecise (might be
overridden by min/max window size specifications, or thrown off by
rounding). So there needs to be a window where we can say "any
imprecision will be rectified by adjusting this window". It would be
awkward to use multiple windows to do that. We could have an implicit
rule saying that the last window in a split might be subject to
adjustment.

In side-window terms, I suppose the 100% window could be considered the
"main" window, in that its size isn't explicit: it's just whatever is
left over after the other windows have been placed appropriately. But
"main" might also imply selection (?), in which case the analogy doesn't
work.

> If all buffers mentioned in the configuration are already visible,
> Gnus won't change the window configuration.  If you always want to
> force the ``right'' window configuration, you can set
>
> Why is this useful and in which occasions does it apply?

Good question. I suppose if the user has manually adjusted a layout,
they might not want Gnus to disturb that if it is functionally the same
as the defined layout. But I really don't know. It doesn't seem very
useful to me, either.

> Finally, it seems that there is no way to "save back" into
> 'gnus-buffer-configuration' a layout that has been obtained by
> "manually" changing an existing layout.  Right?  Wouldn't that be
> desirable?

Could be... We'd have to translate buffers back to windows using
`gnus-window-to-buffer', then reconstruct the current window config into
the "split" format, and put that layout into
`gnus-buffer-configuration'. But that would only work for the current
session. I guess I don't quite see the utility, unless I'm
misunderstanding what you mean?

Thanks for the review!

Eric