Doc: Add layout documentation

1 files changed, 74 insertions, 0 deletions

diff --git a/doc/river-layouts.1.scd b/doc/river-layouts.1.scd
new file mode 100644
index 0000000..92fc2db
--- /dev/null
+++ b/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)
+