From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.devel Subject: Re: Understanding atomic window groups Date: Tue, 11 Jun 2019 14:07:12 -0700 Message-ID: <87muinzv9b.fsf@ericabrahamsen.net> References: <87tvdmqsxq.fsf@ericabrahamsen.net> <0a820a2c-8b37-469e-6b0e-61b126b6c7b8@gmx.at> <87lfyxszb5.fsf@ericabrahamsen.net> <875zpzedy5.fsf@ericabrahamsen.net> <171bed6b-96d6-0fa0-f4f4-b09cb72c7192@gmx.at> <87lfyucxfx.fsf@ericabrahamsen.net> <26d5d317-df88-fed9-1eb5-e5f0cb07bd25@gmx.at> <878suibcu8.fsf@ericabrahamsen.net> <52ea0859-0e57-b2a9-5798-8328596b9630@gmx.at> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="96444"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 11 23:12:34 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hao4H-000Owe-I7 for ged-emacs-devel@m.gmane.org; Tue, 11 Jun 2019 23:12:33 +0200 Original-Received: from localhost ([::1]:55452 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hao4G-00024O-Gg for ged-emacs-devel@m.gmane.org; Tue, 11 Jun 2019 17:12:32 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59021) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hanzM-00065E-Mj for emacs-devel@gnu.org; Tue, 11 Jun 2019 17:07:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hanzK-0003An-M0 for emacs-devel@gnu.org; Tue, 11 Jun 2019 17:07:28 -0400 Original-Received: from [195.159.176.226] (port=50636 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hanzK-00039A-DN for emacs-devel@gnu.org; Tue, 11 Jun 2019 17:07:26 -0400 Original-Received: from list by blaine.gmane.org with local (Exim 4.89) (envelope-from ) id 1hanzG-000J49-Rm for emacs-devel@gnu.org; Tue, 11 Jun 2019 23:07:22 +0200 X-Injected-Via-Gmane: http://gmane.org/ Cancel-Lock: sha1:G37Ojvh90QJILawnUTOICk4kKtc= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 195.159.176.226 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:237444 Archived-At: --=-=-= Content-Type: text/plain martin rudalics 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... --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=gnus-window-docs.diff Content-Transfer-Encoding: 8bit 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 --=-=-=--