From 6bae8efe01b448ae7ea98201dc203fc702316564 Mon Sep 17 00:00:00 2001 From: Isaac Freund Date: Tue, 16 Apr 2024 13:48:39 +0200 Subject: [PATCH] docs: freshen up readme with text from website --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 93e29b5..fc00bb8 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ River is a dynamic tiling Wayland compositor with flexible runtime configuration. +https://isaacfreund.com/software/river + Install from your [package manager](https://repology.org/project/river/versions) — Join us at [#river](https://web.libera.chat/?channels=#river) on irc.libera.chat — Read our man pages, [wiki](https://codeberg.org/river/wiki), and @@ -24,15 +26,30 @@ That said, I do my best to avoid gratuitous breaking changes and bugs/crashes should be rare. If you find a bug don't hesitate to [open an issue](https://codeberg.org/river/river/issues/new/choose).* -## Design goals +## Features -- Simple and predictable behavior, river should be easy to use and have a -low cognitive load. -- Window management based on a stack of views and tags. -- Dynamic layouts generated by external, user-written executables. A default -`rivertile` layout generator is provided. -- Scriptable configuration and control through a custom Wayland protocol and -separate `riverctl` binary implementing it. +Currently river's window management style is quite similar to +[dwm](http://dwm.suckless.org), [xmonad](https://xmonad.org), and other classic +dynamic tiling X11 window managers. Windows are automatically arranged in a tiled +layout and shifted around as windows are opened/closed. + +Rather than having the tiled layout logic built into the compositor process, +river uses a [custom Wayland +protocol](https://codeberg.org/river/river/src/branch/master/protocol/river-layout-v3.xml) +and separate "layout generator" process. A basic layout generator, `rivertile`, +is provided but users are encouraged to use community-developed [layout +generators](https://codeberg.org/river/wiki/src/branch/master/pages/Community-Layouts.md) +or write their own. Examples in C and Python may be found +[here](https://codeberg.org/river/river/src/branch/master/contrib). + +Tags are used to organize windows rather than workspaces. A window may be +assigned to one or more tags. Likewise, one or more tags may be displayed on a +monitor at a time. + +River is configured at runtime using the `riverctl` tool. It can define +keybindings, set the active layout generator, configure input devices, and more. +On startup, river runs a user-defined init script which usually runs `riverctl` +commands to set up the user's configuration. ## Building @@ -85,6 +102,31 @@ in the example directory. For complete documentation see the `river(1)`, `riverctl(1)`, and `rivertile(1)` man pages. +## Future Plans + +Currently details such as how tags work across multiple monitors are not +possible for users to configure. It would be possible to extend river's source +code to allow more flexibility here but this comes at the cost of complexity and +there will always be someone who prefers something slightly different. + +My long term plan to address this is to move as much window management policy as +possible out of the river compositor process and into the "layout generator" +process which will need to be renamed to "window manager." This will give users +much more power and control over river's behavior and also enable some really +cool workflows. For example, it would be possible to write a window manager in +lisp and use hot code reloading to edit its behavior it while it is running. + +This is a non-trivial architectural change and will take a while to implement. I +plan to focus on this change for the 0.4.0 release cycle. Unfortunately, it will +almost certainly break existing river configurations as well. I think the +benefits outweigh that downside though and I will do my best to offer a +reasonable upgrade path. + +## Donate + +If my work on river adds value to your life and you'd like to support me +financially you can find donation information [here](https://isaacfreund.com/donate/). + ## Licensing River is released under the GNU General Public License v3.0 only.