Merge pull request #84 from Eisfreak7/master

Improve hook script documentation

diff --git a/README.md b/README.md
index dc7ee93b99673babefc6c8abc1f1c36e1021d8d7..40588558316f32aad26699d2be99d70466254d2d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,10 +1,13 @@
-# autorandr 
+# autorandr
+
 Automatically select a display configuration based on connected devices
 
 ## Branch information
 
 This is a compatible Python rewrite of
-[wertarbyte/autorandr](https://github.com/wertarbyte/autorandr). Contributions for bash-completion, fd.o/XDG autostart, Nitrogen, pm-utils, and systemd can be found under [contrib](contrib/).
+[wertarbyte/autorandr](https://github.com/wertarbyte/autorandr). Contributions
+for bash-completion, fd.o/XDG autostart, Nitrogen, pm-utils, and systemd can be
+found under [contrib](contrib/).
 
 The original [wertarbyte/autorandr](https://github.com/wertarbyte/autorandr)
 tree is unmaintained, with lots of open pull requests and issues. I forked it
@@ -22,7 +25,7 @@ If you are interested in why there are two versions around, see
 [#8](https://github.com/phillipberndt/autorandr/issues/8) and
 especially
 [#12](https://github.com/phillipberndt/autorandr/issues/12)
-if you are unhappy with this version and would like to contibute to the bash
+if you are unhappy with this version and would like to contribute to the bash
 version.
 
 ## License information and authors
@@ -48,10 +51,12 @@ Contributors to this version of autorandr are:
 * stormc
 * tachylatus
 * Timo Bingmann
+* Timo Kaufmann
 * Tomasz Bogdal
 * Victor Häggqvist
 
 ## Installation/removal
+
 You can use the `autorandr.py` script as a stand-alone binary. If you'd like to
 install it as a system-wide application, there is a Makefile included that also
 places some configuration files in appropriate directories such that autorandr
@@ -64,6 +69,9 @@ For Debian-based distributions (including Ubuntu) it is recommended to call
 On Arch Linux, there is [an aur package
 available](https://aur.archlinux.org/packages/autorandr-git/).
 
+autorandr is also packaged in the [nix package manager](https://nixos.org/nix/)
+repositories.
+
 On other distributions you can install autorandr by calling `make install` and
 remove it by calling `make uninstall`. Run `make` without arguments to obtain a
 list of what exactly will be installed.
@@ -77,7 +85,7 @@ If you prefer `pip` over your package manager, you can install autorandr with:
 
 or simply
 
-       sudo pip install autorandr
+    sudo pip install autorandr
 
 if you prefer to use a stable version.
 
@@ -123,24 +131,54 @@ names in your configuration directory to have autorandr use any of them
 as the default configuration without you having to change the system-wide
 configuration.
 
-Another script called `postswitch` can be placed in the directory
-`~/.config/autorandr` (or `~/.autorandr` if you have an old installation) as
-well as in all profile directories: The scripts are executed after a mode
-switch has taken place and can notify window managers or other applications
-about it. The same holds for `preswitch`, which is executed before the switch
-takes place, and `postsave`, which is executed after a profile was
-stored/altered.
+## Hook scripts
+
+Three more scripts can be placed in the configuration directory (as 
+(as defined by the [XDG spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
+usually `~/.config/autorandr` or `~/.autorandr` if you have an old installation
+for user configuration and `/etc/xdg/autorandr` for system wide configuration):
+
+- `postswitch` is executed *after* a mode switch has taken place. This can be
+  used to notify window managers or other applications about the switch.
+- `preswitch` is executed *before* a mode switch takes place.
+- `postsave` is executed after a profile was stored or altered.
+- `predetect` is executed before autorandr attempts to run xrandr. 
+
+These scripts must be executable and can be placed directly in the configuration
+directory, where they will always be executed, or in the profile subdirectories,
+where they will only be executed on changes regarding that specific profile.
+
+Instead (or in addition) to these scripts, you can also place as many executable
+files as you like in subdirectories called `script_name.d` (e.g. `postswitch.d`).
+
+If a script with the same name occurs multiple times, user configuration
+takes precedence over system configuration (as specified by the
+[XDG spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html))
+and profile configuration over general configuration.
+
+As a concrete example, suppose you have the files
+
+- `/etc/xdg/autorandr/postswitch`
+- `~/.config/autorandr/postswitch`
+- `~/.config/autorandr/postswitch.d/notify-herbstluftwm`
+- `~/.config/autorandr/docked/postswitch`
+
+and switch from `mobile` to `docked`. Then
+`~/.config/autorandr/docked/postswitch` is executed, since the profile specific
+configuration takes precedence, and
+`~/.config/autorandr/postswitch.d/notify-herbstluftwm` is executed, since
+it has a unique name.
+
+If you switch back from `docked` to `mobile`, `~/.config/autorandr/postswitch`
+is executed instead of the `mobile` specific `postswitch`.
+
+In these scripts, some of autorandr's state is exposed as environment variables
+prefixed with `AUTORANDR_`. The most useful one is `$AUTORANDR_CURRENT_PROFILE`.
 
 If you experience issues with xrandr being executed too early after connecting
-a new monitor, then you can create a script `predetect`, which will be executed
-before autorandr attempts to run xrandr. Place e.g. `sleep 1` into that file
-to make autorandr wait a second before running xrandr.
-
-All scripts can also be placed in any of the `$XDG_CONFIG_DIRS`. In addition to
-the script names themselves, any executables in subdirectories named
-`script_name.d` (e.g. `postswitch.d`) are executed as well. In scripts, some of
-autorandr's state is exposed as environment variables prefixed with `AUTORANDR_`.
-The most useful one is `$AUTORANDR_CURRENT_PROFILE`.
+a new monitor, then you can use a `predetect` script to delay the execution.
+Write e.g. `sleep 1` into that file to make autorandr wait a second before
+running `xrandr`.
 
 ## Changelog