docs: improve startup and config information

2 files changed, 38 insertions, 39 deletions

diff --git a/README.md b/README.md
index b64a611..38d6e37 100644
--- a/README.md
+++ b/README.md
@@ -42,48 +42,33 @@ installed:
 *Note: NixOS users may refer to the
 [Building on NixOS wiki page](https://github.com/ifreund/river/wiki/Building-on-NixOS)*
 
-Then run, for example,
+Then run, for example:
 ```
-zig build -Drelease-safe=true --prefix /usr/local install
+zig build -Drelease-safe=true --prefix /usr install
 ```
-to build and install the binaries and man pages to `/usr/local/bin` and
-`/usr/local/share/man`. To enable experimental Xwayland support pass the
-`-Dxwayland=true` option as well.
+To enable experimental Xwayland support pass the `-Dxwayland=true` option as well.
 
 ## Usage
 
 River can either be run nested in an X11/wayland session or directly
 from a tty using KMS/DRM.
 
-River has no keybindings by default; mappings can be created using the `map`
-command of `riverctl`. Generally, creating mappings and other configuration is
-done with a shell script. River will execute any arbitrary shell command passed
-with the `-c` flag during startup. For example:
+On startup river will look for and run an executable file at one of the
+following locations, checked in the order listed:
 
-```
-river -c /path/to/config.sh
-```
-
-An example script with sane defaults is provided [here](contrib/config.sh) in
-the contrib directory.
-
-For a complete list of commands see the `riverctl(1)` man page.
+- `$XDG_CONFIG_HOME/river/init`
+- `$HOME/.config/river/init`
+- `/etc/river/init`
 
-Keyboard configuration is not yet implemented in river, but since river uses
-libxkbcommon you may use the following environment variables to set defaults:
+Usually this executable init file will be a shell script invoking riverctl
+to create mappings and preform other configuration.  The init file path may
+be overridden with the `-c` flag.
 
-- `XKB_DEFAULT_RULES`
-- `XKB_DEFAULT_MODEL`
-- `XKB_DEFAULT_LAYOUT`
-- `XKB_DEFAULT_VARIANT`
-- `XKB_DEFAULT_OPTIONS`
+An example init script with sane defaults is provided [here](example/init)
+in the example directory and installed to `/etc/river/init`.
 
-Possible values for these variables can be found in the `xkeyboard-config(7)`
-man page. For example, to use a dvorak layout one could start river with
-
-```
-XKB_DEFAULT_LAYOUT="us(dvorak)" river
-```
+For a complete list of commands and documentation see the `riverctl(1)`
+man page.
 
 ## Development
 
diff --git a/doc/river.1.scd b/doc/river.1.scd
index b20bd7a..9d5f5b0 100644
--- a/doc/river.1.scd
+++ b/doc/river.1.scd
@@ -16,13 +16,9 @@ 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.
+	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.
 
 *-l* _log_level_
 	Set the log level of river to a value from 0 to 7 with 0 being the
@@ -31,8 +27,20 @@ on wlroots and written in Zig.
 
 # CONFIGURATION
 
-Experimental XWayland support can be enabled on compile-time with the
-_-Dxwayland=true_ flag.
+On startup river will look for and run an executable file at one of the
+following locations, checked in the order listed:
+
+- $XDG_CONFIG_HOME/river/init
+- $HOME/.config/river/init
+- /etc/river/init
+
+This executable init file will be run after river's wayland server is
+initialized but before entering the main loop. If the process started by
+this flag is still running when river exits, river will send SIGTERM and
+and wait for it to terminate.
+
+Usually this will be a shell script invoking *riverctl*(1) to create mappings,
+start programs such as a status bar, and preform other configuration.
 
 # ENVIRONMENT
 
@@ -45,6 +53,12 @@ The following environment variables are used to configure the keyboard. See
 - XKB_DEFAULT_OPTIONS
 - XKB_DEFAULT_RULES
 
+# EXAMPLES
+
+Set the keyboard layout to colemak:
+
+	XKB_DEFAULT_LAYOUT="us(colemak)" river
+
 # AUTHORS
 
 Maintained by Isaac Freund <ifreund@ifreund.xyz> who is assisted by open