feat(api): make nvim_open_win support non-floating windows (#25550)

Adds support to `nvim_open_win` and `nvim_win_set_config` for creating
and manipulating split (non-floating) windows.

1 files changed, 29 insertions, 9 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 1831b78e9e..89d2860ad2 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3093,18 +3093,28 @@ nvim_win_text_height({window}, {*opts})               *nvim_win_text_height()*
 Win_Config Functions                                          *api-win_config*
 
 nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
-    Open a new window.
+    Opens a new split window, or a floating window if `relative` is specified,
+    or an external window (managed by the UI) if `external` is specified.
 
-    Currently this is used to open floating and external windows. Floats are
-    windows that are drawn above the split layout, at some anchor position in
-    some other window. Floats can be drawn internally or by external GUI with
-    the |ui-multigrid| extension. External windows are only supported with
-    multigrid GUIs, and are displayed as separate top-level windows.
+    Floats are windows that are drawn above the split layout, at some anchor
+    position in some other window. Floats can be drawn internally or by
+    external GUI with the |ui-multigrid| extension. External windows are only
+    supported with multigrid GUIs, and are displayed as separate top-level
+    windows.
 
     For a general overview of floats, see |api-floatwin|.
 
-    Exactly one of `external` and `relative` must be specified. The `width`
-    and `height` of the new window must be specified.
+    The `width` and `height` of the new window must be specified when opening
+    a floating window, but are optional for normal windows.
+
+    If `relative` and `external` are omitted, a normal "split" window is
+    created. The `win` property determines which window will be split. If no
+    `win` is provided or `win == 0`, a window will be created adjacent to the
+    current window. If -1 is provided, a top-level split will be created.
+    `vertical` and `split` are only valid for normal windows, and are used to
+    control split direction. For `vertical`, the exact direction is determined
+    by |'splitright'| and |'splitbelow'|. Split windows cannot have
+    `bufpos`/`row`/`col`/`border`/`title`/`footer` properties.
 
     With relative=editor (row=0,col=0) refers to the top-left corner of the
     screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
@@ -3127,6 +3137,13 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
           {relative='win', width=12, height=3, bufpos={100,10}})
 <
 
+    Example (Lua): vertical split left of the current window >lua
+        vim.api.nvim_open_win(0, false, {
+          split = 'left',
+          win = 0
+        })
+<
+
     Attributes: ~
         not allowed when |textlock| is active
 
@@ -3142,7 +3159,8 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                     • "cursor" Cursor position in current window.
                     • "mouse" Mouse position
 
-                  • win: |window-ID| for relative="win".
+                  • win: |window-ID| window to split, or relative window when
+                    creating a float (relative="win").
                   • anchor: Decides which corner of the float to place at
                     (row,col):
                     • "NW" northwest (default)
@@ -3239,6 +3257,8 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                   • fixed: If true when anchor is NW or SW, the float window
                     would be kept fixed even if the window would be truncated.
                   • hide: If true the floating window will be hidden.
+                  • vertical: Split vertically |:vertical|.
+                  • split: Split direction: "left", "right", "above", "below".
 
     Return: ~
         Window handle, or 0 on error