Re: Understanding atomic window groups

[Eric Abrahamsen <eric@ericabrahamsen.net>]

[-- 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