Re: Add function to rotate/transpose all windows

[martin rudalics <rudalics@gmx.at>]

 >> Alternatively, we could give 'window-tree' an optional PIXELWISE
 >> argument so it returns the pixel edges of windows.
 >
 > You decide

Better not - the fact that 'window-tree' does not report the edges of
live windows constitutes bad design.  Let's not support it.  Rather
let's make it a normal function called 'window-tree-pixel-sizes'.  I
would write its doc string as

   (defun window-tree-pixel-sizes (window &optional next)
     "Return pixel sizes of all windows rooted at WINDOW.
   The return value is a list where each window is represented either by a
   triple whose first element is either t for an internal window that is a
   horizontal combination, nil for an internal window that is a vertical
   combination, or the window itself for a live window.  The second element
   is a cons of the pixel height and pixel width of the window.  The third
   element is specified for internal windows only and recursively lists
   that window's child windows using the same triple structure."

but you would have to check whether it really does what I wrote.

 > (defun rotate-windows-anticlockwise (&optional frame-or-window)
 >   "Rotate windows of FRAME-OR-WINDOW 90 degrees anticlockwise.
 > See `rotate-windows-clockwise' for more."

I think it's better to write out the full doc-string here first and
in a final sentence say

   See `rotate-windows-clockwise' for how to rotate windows in the
   opposite direction.

 > (defun rotate-windows-clockwise (&optional frame-or-window)
 >   "Rotate windows of FRAME-OR-WINDOW clockwise by 90 degrees.
 > FRAME-OR-WINDOW must be a live frame or window and defaults to the
 > selected frame. If FRAME-OR-WINDOW is a frame, rotate from the root
 > window of the frame, otherwise rotate from FRAME-OR-WINDOW."

Please add two spaces after the end of each sentence like

   selected frame.  If FRAME-OR-WINDOW is a frame, ...

Also I would omit the "from" in "rotate from".  And I would add a cross
reference to 'rotate-windows-anticlockwise' at the end.

 > (defun flip-windows-horizontally (&optional frame-or-window)
 >   "Horizontally flip windows of FRAME-OR-WINDOW.
 > FRAME-OR-WINDOW must be a live frame or window and defaults to the
 > selected frame. If FRAME-OR-WINDOW is a frame, flip from the root
 > window of the frame, otherwise flip from FRAME-OR-WINDOW."

Here you should probably first say what "flip" means.  It's obvious when
you have a frame with two side-by-side live windows.  It's already less
obvious with three side-by-side windows and even less so with more
complex layouts.

 > (defun transpose-windows (&optional frame-or-window)
 >   "Transpose windows of FRAME-OR-WINDOW.
 > Windows are rearanged such that where an horizontal split was used, an
 > vertical one is instead, and vice versa. FRAME-OR-WINDOW must be a live
 > frame or window and defaults to the selected frame. If FRAME-OR-WINDOW
 > is a frame, transpose from the root window of the frame, otherwise
 > transpose from FRAME-OR-WINDOW."

Please us active voice like

   Rearrange windows such that where a horizontal split was used a
   vertical one is used instead, and vice versa.

and again remove the "from" in "transpose from".

 > (defun transpose-windows--rearrange (frame-or-window conf norm-size)

I'd call this just 'window--transpose'.

 > "Rearrange windows of FRAME-OR-WINDOW recursively.
 > CONF should be a cons cell: (HORIZONTAL-SPLIT . VERTICAL-SPLIT) where
 > horizontal split is called when splitting a window that was previously
 > horizontally split, and VERTICAL-SPLIT for a window that was previously
 > vertically split.

CONF is confusing.  Why is it a cons cell in the first place?  Wouldn't
a simple boolean - t for horizontal and nil for vertical - suffice?  If
not, please explain why.

 > When is NORM-SIZE non-nil, the size argument of the

I think it's just the pixel size and not the normal size, right?  Also
you should write it as "When NORM-SIZE is non-nil ..."

 > 		  (frame-root-window frame-root-window)

This doesn't look right.

 > 	(message "Not enough windows")

Better is "No windows to transpose".

 >       (let* ((fwin (frame-first-window rwin))

Note that 'frame-first-window' returns the first live window on its
frame.  What if you want to flip some child windows only?

 > 	(select-window selwin)))))

should become (set-frame-selected-window selwin) for the case that you
rotate windows on a non-selected frame.

 > (defun transpose-windows--rearrange-1 (subtree cwin conf norm-size)

And this I'd call 'window--transpose-1'

 >   "Subroutine of `transpose-windows--rearrange'."

Again please describe all arguments in the doc-string.

And please handle the case where a frame contains side windows.  Just
replace 'frame-root-window' with 'window--main-window' everywhere and
talk about "main window" instead of "root window".

Thanks, martin