Re: Prefer to split along the longest edge

[martin rudalics <rudalics@gmx.at>]

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

It's still hard to read for me.  I'd write is as follows:

The variable `split-window-preferred-direction' prescribes an order of
directions in which Emacs should try to split WINDOW.  If that order
mandates to start with a vertical split and `split-height-threshold'
specifies an integer that is at least as large a WINDOW's height, split
WINDOW into two windows one below the other and return the lower one.
If that order mandates to start with a horizontal split and
`split-width-threshold' specifies an integer that is at least as large
as WINDOW's width, split WINDOW into two windows side by side and return
the one on the right.

In either case, if the first attempt to split WINDOW fails, try to split
the window in the other direction in the same manner as described above.
If that attempts fail too and WINDOW is the only window on its frame,
try splitting WINDOW into two windows one below the other disregarding
the value of `split-height-threshold' and return the window on the
bottom.

Then the doc-string of 'split-window-preferred-direction' should say
that its value implies an order of operations 'split-window-sensibly'
will try and that that order may depend on the orientation of the frame.
While the frame orientation is processed in 'split-window-sensibly', I
wouldn't mention it there to avoid describing it twice.

BTW the doc-string of 'split-window-preferred-direction' should also say
that it applies to 'split-window-sensibly' only and not to any other
functions that split windows.

martin