Doc: Add layout documentation

build.zig

@@ -210,6 +210,7 @@ const ScdocStep = struct {
     const scd_paths = [_][]const u8{
         "doc/river.1.scd",
         "doc/riverctl.1.scd",
+        "doc/river-layouts.1.scd",
     };
 
     builder: *std.build.Builder,

doc/river-layouts.1.scd

@@ -0,0 +1,74 @@
+RIVER-LAYOUTS(7) "github.com/ifreund/river"
+
+# NAME
+river-layouts - Details on layout generators for river
+
+# DESCRIPTION
+River can use external window management layouts. To get such a layout, river
+will run an executable and parse its output. This document outlines how such
+a layout generator interacts with river.
+
+# INPUT
+When running the executable, river will provide it with five parameters which
+are appended to the end of the command in the following order:
+
+. The amount of visible clients (integer)
+. The amount of views dedicated as master (integer)
+. The screen size multiplier for the master area (float between 0.0 and 1.0)
+. The useable width of the output (integer)
+. The useable height of the output (integer)
+
+A layout generator may choose to ignore any of these values except
+for the first one.
+
+# OUTPUT
+River expects four integer values for each window: The x position, the y
+position, the width and the height. These must be separated by spaces. A
+window configuration having fewer or more than four values is an error and will
+cause river to fall back the full layout.
+
+A layout generator needs to output position and size for every visible window.
+The window configurations are separated by a newline. Too few or too many
+outputted window configurations is an error and will cause river to fall back
+to the full layout.
+
+River will apply the position and dimensions in the order they are outputted to
+the visible windows in the stack from top to bottom.
+
+The output of a layout generator is not required to remain the same when called
+with identical parameters. Layouts are allowed to also depend on external
+factors or be completely random.
+
+# WINDOW DIMENSIONS and POSITION
+Layout generators are not supposed to include padding or leave space for window
+borders. The window dimensions will be shrunk by river to make space for these.
+River enforces a minimal window width and height of 50.
+
+Layout generators operate on a special coordinate grid from 0 to the maximum
+useable width or height of an output with the coordinate 0-0 being positioned at
+the top-left corner of the useable area of an output. While layout generators
+are free to place windows everywhere (including coordinates below zero or above
+the maximum width or height of an output), beware that the relative positioning
+of this grid on the screen can not be expected to remain constant. River applies
+an offset to window positions, depending on outer padding and the presence of
+desktop widgets like bars. Layout generators can therefore not position windows
+at exact screen coordinates.
+
+Layout generators are not required to make use of the entire available space.
+Windows may overlap.
+
+# EXAMPLE
+Below is an example output of a layout generator for four visible windows. In
+this example layout all four windows have a size of 500 by 500 and are arranged
+in a grid.
+
+```
+0 0 500 500
+500 0 500 500
+0 500 500 500
+500 500 500 500
+```
+
+# SEE ALSO
+*river*(1), *riverctl*(1)
+

doc/riverctl.1.scd

@@ -31,8 +31,13 @@ used to control and configure river.
 *focus-view* *next*|*previous*
 	Focus next or previous view in the stack.
 
-*layout* *top-master*|*right-master*|*bottom-master*|*left-master*|*full*
-	Change the view layout.
+*layout* *full*|_command_
+	Provide a command which river will use for generating the layout of
+	non-floating windows on the currently focused output. See
+	*river-layouts*(1) for details on the expected formatting of the output
+	of layout commands. Alternatively, "full"can be given instead of a
+	command to cause river to use its single internal layout, in which
+	windows span the entire width and height of the output.
 
 *mod-master-count* _integer_
 	Increase or decrease the number of master views. _integer_ can be