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