diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/river-layouts.7.scd | 33 | ||||
| -rw-r--r-- | doc/river.1.scd | 25 | ||||
| -rw-r--r-- | doc/riverctl.1.scd | 129 | ||||
| -rw-r--r-- | doc/rivertile.1.scd | 2 |
4 files changed, 103 insertions, 86 deletions
diff --git a/doc/river-layouts.7.scd b/doc/river-layouts.7.scd index 4692168..06ace54 100644 --- a/doc/river-layouts.7.scd +++ b/doc/river-layouts.7.scd @@ -1,14 +1,17 @@ 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. +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: @@ -22,10 +25,11 @@ 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. +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 @@ -40,24 +44,26 @@ 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. +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. @@ -76,4 +82,5 @@ source contributors. For more information about river's development, see <https://github.com/ifreund/river>. # SEE ALSO + *river*(1), *riverctl*(1), *rivertile*(1) diff --git a/doc/river.1.scd b/doc/river.1.scd index ef16577..c08a696 100644 --- a/doc/river.1.scd +++ b/doc/river.1.scd @@ -1,7 +1,8 @@ RIVER(1) "github.com/ifreund/river" "General Commands Manual" + # NAME -river - dynamic tiling Wayland compositor +river - Dynamic tiling Wayland compositor # SYNOPSIS @@ -9,19 +10,19 @@ river - dynamic tiling Wayland compositor # DESCRIPTION -*river* is a dynamic tiling Wayland compositor inspired by dwm and -bspwm based on wlroots and written in Zig. +*river* is a dynamic tiling Wayland compositor inspired by dwm and bspwm based +on wlroots and written in Zig. # OPTIONS *-c* _shell_command_ - Run a shell command or give the path to a script that will be run - after river's wayland server is initialized but before entering the - main loop. You may use this to configure river and define keymaps - using *riverctl*(1), start programs such as a status bar, or perhaps - run a service manager. If the process started by this flag is still - running when river exits, river will send SIGTERM and and wait for it - to terminate. + Run a shell command or give the path to a script that will be run after + river's wayland server is initialized but before entering the main + loop. You may use this to configure river and define keymaps using + *riverctl*(1), start programs such as a status bar, or perhaps run a + service manager. If the process started by this flag is still running + when river exits, river will send SIGTERM and and wait for it to + terminate. *-l* _log_level_ Set the log level of river to a value from 0 to 7 with 0 being the @@ -30,8 +31,8 @@ bspwm based on wlroots and written in Zig. # CONFIGURATION -You can define the list of programs which should float in _Config.zig_. -Make your changes and recompile. +You can define the list of programs which should float in _Config.zig_. Make +your changes and recompile. Experimental XWayland support can be enabled on compile-time with the _-Dxwayland=true_ flag. diff --git a/doc/riverctl.1.scd b/doc/riverctl.1.scd index b1188fb..4d87300 100644 --- a/doc/riverctl.1.scd +++ b/doc/riverctl.1.scd @@ -1,7 +1,8 @@ RIVERCTL(1) "github.com/ifreund/river" "General Commands Manual" + # NAME -riverctl - command-line interface for controlling river +riverctl - Command-line interface for controlling river # SYNOPSIS @@ -9,8 +10,8 @@ riverctl - command-line interface for controlling river # DESCRIPTION -*riverctl* is a command-line interface inspired by bspc from bspwm -used to control and configure river. +*riverctl* is a command-line interface inspired by bspc from bspwm used to +control and configure river. # COMMANDS @@ -20,15 +21,16 @@ used to control and configure river. Close the focused view. *csd-filter-add* _app-id_ - Add an app-id to the CSD filter list. Windows with this app-id are allowed - to use client side decoration instead of the default server side decoration. + Add an app-id to the CSD filter list. Windows with this app-id are + allowed to use client side decoration instead of the default server + side decoration. *exit* Exit the compositor, terminating the Wayland session. *float-filter-add* _app-id_ - Add an app-id to the float filter list. Windows with this app-id will start - floating. + Add an app-id to the float filter list. Windows with this app-id will + start floating. *focus-output* *next*|*previous* Focus next or previous output. @@ -54,15 +56,16 @@ used to control and configure river. the whole screen. *move* *up*|*down*|*left*|*right* _delta_ - Move the focused view in the specified direction by _delta_. The view will - be set to floating. + Move the focused view in the specified direction by _delta_. The view + will be set to floating. *resize* *horizontal*|*vertical* _delta_ - Resize the view in the given orientation by _delta_. The view will be set to - floating. + Resize the view in the given orientation by _delta_. The view will be + set to floating. *snap* *up*|*down*|*left*|*right* - Snap the view to the specified screen edge. The view will be set to floating. + Snap the view to the specified screen edge. The view will be set to + floating. *send-to-output* *next*|*previous* Send the focused view to the next or the previous output. @@ -73,30 +76,29 @@ used to control and configure river. interpreted by your shell before the command gets passed to _/bin/sh_. *swap* *next*|*previous* - Swap the focused window with the next/previous visible non-floating window. - When the focused view is the first view there is no previous view. - In this case *previous* swaps with the last view. - *next* behaves analogous. + Swap the focused window with the next/previous visible non-floating + window. When the focused view is the first view there is no previous + view. In this case *previous* swaps with the last view. *next* behaves + analogous. *toggle-float* - If the focused view is floating, make it tiled. If it is tiled, make - it floating. + If the focused view is floating, make it tiled. If it is tiled, make it + floating. *toggle-fullscreen* Toggle the fullscreen state of the focused view. *zoom* - Bump the focused view to the top of the layout stack to make it the - new master. + Bump the focused view to the top of the layout stack to make it the new + master. ## ACTIONS ON TAGS -Tags are like workspaces but more flexible: You can assign views to -multiple tags and look at multiple tags at once. A _tagmask_ is used -to represent which tags are visible. The following commands take a -_tagmask_ in base 10 as argument but _tagmasks_ are best understood in -binary: 000000001 means that the first tag is visible; 111111111 means -that tag 1 through 9 are visible. +Tags are like workspaces but more flexible: You can assign views to multiple +tags and look at multiple tags at once. A _tagmask_ is used to represent which +tags are visible. The following commands take a _tagmask_ in base 10 as +argument but _tagmasks_ are best understood in binary: 000000001 means that the +first tag is visible; 111111111 means that tag 1 through 9 are visible. *set-focused-tags* _tagmask_ Show the tags specified with _tagmask_. @@ -113,7 +115,8 @@ that tag 1 through 9 are visible. ## CONFIGURATION COMMANDS *attach-mode* *top*|*bottom* - Configure where new views should attach in the view stack for the currently focused output. + Configure where new views should attach in the view stack for the + currently focused output. *background-color* _#RRGGBB_|_#RRGGBBAA_ Set the background color. @@ -134,21 +137,24 @@ that tag 1 through 9 are visible. Switch to given mode if it exits. *focus-follows-cursor* *disabled*|*normal*|*strict* - When _disabled_ moving the cursor will not influence the focus. This is the default setting. - If set to _normal_ moving the cursor over a window will focus that window. - The focus still can be changed and moving the cursor within the (now unfocused) window will - not change the focus to that window but let the currently focused window in focus. - When set to _strict_ this is not the case. The focus will be updated on every cursor movement. + When _disabled_ moving the cursor will not influence the focus. This is + the default setting. If set to _normal_ moving the cursor over a window + will focus that window. The focus still can be changed and moving the + cursor within the (now unfocused) window will not change the focus to + that window but let the currently focused window in focus. When set to + _strict_ this is not the case. The focus will be updated on every + cursor movement. - When the to be focused view is on another output than the currently focused output the view's - output is focused. + When the to be focused view is on another output than the currently + focused output the view's output is focused. *map* [-release] _mode_ _modifiers_ _key_ _command_ - _mode_ is either "normal" (the default mode), "locked" (the mode entered when - an input inhibitor such as a lock screen is active) or a mode created with *declare-mode*. - If _-release_ is specified the mapping is executed on key release rather than key press. - _modifiers_ is a list of one or more of the following - modifiers separated with a plus sign: + _mode_ is either "normal" (the default mode), "locked" (the mode + entered when an input inhibitor such as a lock screen is active) or a + mode created with *declare-mode*. If _-release_ is specified the + mapping is executed on key release rather than key press. _modifiers_ + is a list of one or more of the following modifiers separated with a + plus sign: - Shift - Lock (Caps lock) @@ -159,16 +165,18 @@ that tag 1 through 9 are visible. - Mod4 (Super, Logo, Windows) - Mod5 - _key_ is an XKB key name. See _/usr/include/xkbcommon/xkbcommon-keysyms.h_ - for a list of special key names. _command_ can be any of the above commands. + _key_ is an XKB key name. See + _/usr/include/xkbcommon/xkbcommon-keysyms.h_ for a list of special key + names. _command_ can be any of the above commands. - A mapping without modifiers can be created by using "None" as sole modifier. + A mapping without modifiers can be created by using "None" as sole + modifier. *map-pointer* _mode_ _modifiers_ _button_ _action_ _mode_ and _modifiers_ are the same as for *map*. - _button_ is the name of a linux input event code. The most commonly used - values are: + _button_ is the name of a linux input event code. The most commonly + used values are: - BTN_LEFT - left mouse button - BTN_RIGHT - right mouse button @@ -184,17 +192,18 @@ that tag 1 through 9 are visible. *opacity* _focused-opacity_ _unfocused-opacity_ _starting-opacity_ _opacity-step_ _opacity-delta-t_ Set the server side opacity of views. - _focused-opacity_ sets the opacity of the focused window, _unfocused-opacity_ - the opacity of every unfocused window while _starting-opacity_ sets the - opacity a window will have at startup before immediately transitioning to - either the focused or unfocused opacity. These settings require a floating - point number from 0.0 (fully transparent) to 1.0 (fully opaque). + _focused-opacity_ sets the opacity of the focused window, + _unfocused-opacity_ the opacity of every unfocused window while + _starting-opacity_ sets the opacity a window will have at startup + before immediately transitioning to either the focused or unfocused + opacity. These settings require a floating point number from 0.0 (fully + transparent) to 1.0 (fully opaque). Opacity transitions can be animated. _opacity-step_ sets the amount the opacity should be increased or decreased per step of the transition. It - requires a floating point number from 0.05 to 1.0. If set to 1.0, animations - are disabled. _opacity-delta-t_ sets the time between the transition steps - in milliseconds. + requires a floating point number from 0.05 to 1.0. If set to 1.0, + animations are disabled. _opacity-delta-t_ sets the time between the + transition steps in milliseconds. *outer-padding* _pixels_ Set the padding around the edge of the screen to _pixels_. @@ -204,21 +213,21 @@ that tag 1 through 9 are visible. repeat delay to _delay_ milliseconds. *unmap* [-release] _mode_ _modifiers_ _key_ - Removes the mapping defined by the arguments *-release*, *modifiers* and *key* from *mode*. - See *map* for an explanation of the arguments. + Removes the mapping defined by the arguments *-release*, *modifiers* + and *key* from *mode*. See *map* for an explanation of the arguments. *unmap-pointer* _mode_ _modifiers_ _button_ - Removes the mapping defined by the arguments *modifiers* and *button* from *mode*. - See *map-pointer* for an explanation of the arguments. + Removes the mapping defined by the arguments *modifiers* and *button* + from *mode*. See *map-pointer* for an explanation of the arguments. *view-padding* _pixels_ Set the padding around the edge of each view to _pixels_. *xcursor-theme* _theme_name_ [_size_] - Set the xcursor theme to _theme_name_ and optionally set the - _size_. The theme of the default seat determines the default - for XWayland and made available through the _XCURSOR_THEME_ and - _XCURSOR_SIZE_ environment variables. + Set the xcursor theme to _theme_name_ and optionally set the _size_. + The theme of the default seat determines the default for XWayland and + made available through the _XCURSOR_THEME_ and _XCURSOR_SIZE_ + environment variables. # EXAMPLES diff --git a/doc/rivertile.1.scd b/doc/rivertile.1.scd index 56530fe..3d5daf8 100644 --- a/doc/rivertile.1.scd +++ b/doc/rivertile.1.scd @@ -2,7 +2,7 @@ RIVERTILE(1) "github.com/ifreund/river" "General Commands Manual" # NAME -rivertile - tiled layout generator for river +rivertile - Tiled layout generator for river # SYNOPSIS |