river/doc/river.1.scd

RIVER(1) "github.com/ifreund/river" "General Commands Manual"

# NAME

river - dynamic tiling Wayland compositor

# SYNOPSIS

*river* [_options_]

# DESCRIPTION

*river* is a dynamic tiling Wayland compositor. Window management is based on
a stack of views laid out dynamically by an external layout generator. Tags
are used instead of workspaces allowing for increased flexibility.

All configuration and control happens at runtime through Wayland protocols,
including several river-specific protocol extensions. The *riverctl*(1)
utility may be used to communicate with river over these protocols.

# OPTIONS

*-h*
	Print a help message and exit.

*-version*
	Print the version number and exit.

*-c* _shell_command_
	Override the default search paths for an init executable: instead
	_shell_command_ will be run with _/bin/sh -c_. See the *CONFIGURATION*
	section for more details.

*-log-level* [*error*|*warn*|*info*|*debug*]
	Set the log level of river. At the *error* log level, only errors
	are logged.  At the *debug* log level, everything is logged including
	verbose debug messages.

# CONFIGURATION

On startup river will run an executable file at $XDG_CONFIG_HOME/river/init if
such an executable exists. If $XDG_CONFIG_HOME is not set, ~/.config/river/init
will be used instead.

The executable init file will be run as a process group leader after river's
Wayland server is initialized but before entering the main loop. On exit,
river will send SIGTERM to this process group.

Usually this executable is a shell script invoking *riverctl*(1) to create
mappings, start programs such as a layout generator or status bar, and
preform other configuration.

# ENVIRONMENT

The following environment variables are used to configure the keyboard. See
*xkeyboard-config*(7) for possible values.

- XKB_DEFAULT_MODEL
- XKB_DEFAULT_LAYOUT
- XKB_DEFAULT_VARIANT
- XKB_DEFAULT_OPTIONS
- XKB_DEFAULT_RULES

# EXAMPLES

Set the keyboard layout to colemak:

	XKB_DEFAULT_LAYOUT="us(colemak)" river

# AUTHORS

Maintained by Isaac Freund <mail@isaacfreund.com> who is assisted by open
source contributors. For more information about river's development, see
<https://github.com/ifreund/river>.

# SEE ALSO

*riverctl*(1), *rivertile*(1)
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00			`RIVER(1) "github.com/ifreund/river" "General Commands Manual"`
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8). 2020-12-12 15:51:51 -08:00
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00			`# NAME`

docs: Improve clarity of river/riverctl man pages 2020-12-30 14:10:41 -08:00			`river - dynamic tiling Wayland compositor`
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00
			`# SYNOPSIS`

docs: add -help and -version options to man pages 2021-07-24 10:42:34 -07:00			`river [_options_]`
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00
			`# DESCRIPTION`

docs: Improve clarity of river/riverctl man pages 2020-12-30 14:10:41 -08:00			`river is a dynamic tiling Wayland compositor. Window management is based on`
			`a stack of views laid out dynamically by an external layout generator. Tags`
			`are used instead of workspaces allowing for increased flexibility.`

docs: assorted fixes/cleanups 2021-10-31 16:29:06 -07:00			`All configuration and control happens at runtime through Wayland protocols,`
docs: Improve clarity of river/riverctl man pages 2020-12-30 14:10:41 -08:00			`including several river-specific protocol extensions. The riverctl(1)`
			`utility may be used to communicate with river over these protocols.`
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00
			`# OPTIONS`

common: use -h instead of -help This doesn't really matter that much as unrecognized options will still trigger a help message to be printed, but -h is much more standard so lets make the predictable choice here while sticking to only single '-' flags. 2021-10-31 16:34:15 -07:00			`-h`
docs: add -help and -version options to man pages 2021-07-24 10:42:34 -07:00			`Print a help message and exit.`

			`-version`
			`Print the version number and exit.`

docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00			`-c _shell_command_`
docs: improve startup and config information 2020-12-30 11:29:45 -08:00			`Override the default search paths for an init executable: instead`
docs: Improve clarity of river/riverctl man pages 2020-12-30 14:10:41 -08:00			`_shell_command_ will be run with _/bin/sh -c_. See the CONFIGURATION`
docs: improve startup and config information 2020-12-30 11:29:45 -08:00			`section for more details.`
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00
river: simplify log levels exposed to the user 2021-07-24 11:45:58 -07:00			`-log-level [error\|warn\|info\|debug]`
			`Set the log level of river. At the error log level, only errors`
			`are logged. At the debug log level, everything is logged including`
			`verbose debug messages.`
cli: allow setting log level with '-l' flag 2020-06-16 17:01:07 -07:00
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00			`# CONFIGURATION`

docs: improve formatting consistency 2021-07-19 17:20:02 -07:00			`On startup river will run an executable file at $XDG_CONFIG_HOME/river/init if`
			`such an executable exists. If $XDG_CONFIG_HOME is not set, ~/.config/river/init`
			`will be used instead.`
docs: improve startup and config information 2020-12-30 11:29:45 -08:00
river: send SIGTERM to init command process group Run the init command in a new process group and send SIGTERM to the entire group on exit. Without doing this, only the sh invocation used for the `sh -c` would receive SIGTERM. This is particularly useful when starting a per-session server manager as the init command. 2021-02-21 13:03:03 -08:00			`The executable init file will be run as a process group leader after river's`
docs: Wayland should always be capitalized This matches the style used on https://wayland.freedesktop.org/ 2021-07-26 03:20:48 -07:00			`Wayland server is initialized but before entering the main loop. On exit,`
river: send SIGTERM to init command process group Run the init command in a new process group and send SIGTERM to the entire group on exit. Without doing this, only the sh invocation used for the `sh -c` would receive SIGTERM. This is particularly useful when starting a per-session server manager as the init command. 2021-02-21 13:03:03 -08:00			`river will send SIGTERM to this process group.`
docs: improve startup and config information 2020-12-30 11:29:45 -08:00
river: remove system /etc dir from init search paths A true "default" config doesn't make sense for river. Everyone who uses river seriously will customize their init script. Futhermore, the current behavior of embedding the install path of the default system config in the river binary is complex and prone to breaking. 2021-07-17 07:04:51 -07:00			`Usually this executable is a shell script invoking riverctl(1) to create`
			`mappings, start programs such as a layout generator or status bar, and`
			`preform other configuration.`
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00
docs: small man pages fixes and updates - Previous hard-coded settings can be now be changes with riverctl or via environment variables - Update "See also" - Mod → Mod1 2020-06-17 01:39:48 -07:00			`# ENVIRONMENT`

			`The following environment variables are used to configure the keyboard. See`
			`xkeyboard-config(7) for possible values.`

			`- XKB_DEFAULT_MODEL`
			`- XKB_DEFAULT_LAYOUT`
			`- XKB_DEFAULT_VARIANT`
			`- XKB_DEFAULT_OPTIONS`
			`- XKB_DEFAULT_RULES`
docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00
docs: improve startup and config information 2020-12-30 11:29:45 -08:00			`# EXAMPLES`

			`Set the keyboard layout to colemak:`

			`XKB_DEFAULT_LAYOUT="us(colemak)" river`

doc: add AUTHORS section to man pages 2020-11-11 11:44:41 -08:00			`# AUTHORS`

doc: update my (Isaac's) email address 2021-10-02 04:01:58 -07:00			`Maintained by Isaac Freund <mail@isaacfreund.com> who is assisted by open`
doc: add AUTHORS section to man pages 2020-11-11 11:44:41 -08:00			`source contributors. For more information about river's development, see`
			`<https://github.com/ifreund/river>.`

docs: use scdoc instead of roff for man pages 2020-06-15 00:51:23 -07:00			`# SEE ALSO`

doc: remove outdated reference to river-layouts(1) 2021-05-03 04:36:52 -07:00			`riverctl(1), rivertile(1)`