Re: Prefer to split along the longest edge

[Eli Zaretskii <eliz@gnu.org>]

> From: Nicolas Desprès <nicolas.despres@gmail.com>
> Date: Wed, 18 Dec 2024 22:08:58 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, juri@linkov.net, emacs-devel@gnu.org
> 
> Thanks Robert and Eli for your review, and sorry for the delayed answer, it has been pretty busy at work
> lately.
> 
> You'll find attached a new version of the patch that should address all your remarks.

Thanks, a few minor nits for the documentation parts below.

> @@ -519,7 +520,9 @@ Window Choice
>  @code{split-width-threshold} is smaller than the window's width, the
>  split puts the new window on the right.  If neither condition holds,
>  Emacs tries to split so that the new window is below---but only if the
> -window was not split before (to avoid excessive splitting).
> +window was not split before (to avoid excessive splitting).  Whether
> +Emacs tries to split the vertical or horizontal edge first, is
> +determined by the value of @code{split-window-preferred-direction}.

Instead of "tries to split the vertical or horizontal edge first", I'd
prefer a simpler "tries first to split vertically or horizontally".
The "edge" part might confuse some readers.

> ++++
> +*** New user option 'split-window-preferred-direction'.
> +Users can now choose which edge (vertical or horizontal) is tried to be
> +split first.

Same rewording here.  "Users can now choose in which direction Emacs
tries to split windows first: vertical or horizontal."

> +(defcustom split-window-preferred-direction 'vertical
> +  "The edge that will be first tried when Emacs need to split a window.

Likewise here: I'd replace "edge" with "direction" or "dimension".

> +When this variable is to `vertical' (the default) Emacs tries to split
                      ^^^^^
"is set to"

> +vertically first and then horizontally.  If set to `horizontal' it does
> +the opposite. When set to `longest', it the first direction tried will
               ^^
Two spaces there.  Also, please use "If set to", not "When set to", to
avoid potential confusion due to misinterpretation of "when" as
something time-related.

> +depends on the frame shape: in landscape orientation it will be like
> +`horizontal', but in portrait it will be like `vertical'.  Basically the
> +longest edge is split first.
   ^^^^^^^^^^^^
"longest dimension", perhaps? or "longest window dimension"?

> +If both `split-width-threshold' and `split-height-threshold' cannot be
> +satisfied, Emacs will fallback to split vertically.
                         ^^^^^^^^
"fall back", two words.  Also, given the effect of this new option, I
think we should say ".. will fall back to splitting vertically,
regardless of the value of this variable."  Otherwise, it is not
immediately clear how this sentence is related to this variable.

> +          (const :tag "Try to split along the longest edge first"

I'd use "the longest dimension" instead of "longest edge".

> +                                                   If the threshold
> +(`split-height-threshold' respectively `split-width-threshold')
> +specifies an integer, WINDOW is at least that threshold lines tall
> +(respectively wide) and can be split (vertically respectively
> +horizontally).

This sentence doesn't look right, and the doc string in general is
hard to read and understand, because it tries to say things too
concisely.  How about this variant:

 WINDOW defaults to the currently selected window.

 If the split-size threshold of the window dimension determined by
 `split-window-preferred-direction' specifies an integer, the
 corresponding dimension of WINDOW is at least that large, then first
 try splitting window in two along that dimension (one below the other
 if splitting vertically, side by side if splitting horizontally).
 The relevant threshold is `split-height-threshold' when splitting
 vertically, and `split-width-threshold' when splitting horizontally.
 If splitting along the preferred dimension fails, try splitting
 WINDOW along the other dimension.  If that also fails, and WINDOW is
 the only window on its frame, try splitting WINDOW vertically
 disregarding the value of `split-height-threshold'.

 If splitting succeeds, return the lower window if splitting
 vertically, the right one if splitting horizontally.  If splitting
 fails, return nil.

Martin, any comments or corrections to the above doc string?