better docs

Author: santikid

README.md

@@ -1,10 +1,12 @@
-# clink
+# clink [conditional symlink farm]
 
-conditional symlink farm manager
+`clink` is a conditional symlink farm manager. You can define features as described in [Configuration](#configuration), 
+with a condition on whether directories tagged with this feature should be symlinked. This condition can 
+either be `all`, the wanted OS (`macos` | `linux`) or a custom command.
 
 ## Usage
 
-`clink link` - creates symlinks based on Configuration
+`clink link` - creates symlinks based on `clink.yaml` in current directory
 
 `clink unlink [-l | --leave-orphans]` - removes symlinks
 
@@ -14,32 +16,42 @@ Clink is configured in a `clink.yaml` file.
 
 ```yaml
 features:
-    - slug: all
-      enabled: all # all, macos, linux or custom command
-      target: ~/   # location to symlink this feature to
-    - slug: mac
-      enabled: macos
-      target: ~/
-    - slug: mac-opt
-      enabled: macos
-      target: /opt/
-    - slug: linux
-      enabled: linux
-      target: ~/
-    - slug: custom
-      # custom enabled commands have to be tagged with !command
-      # the specified command needs to return exit code 0 to count as enabled
-      enabled: !command /some/custom/script
-      target: ~/
+  - slug: all
+    enabled: all # all, macos, linux or custom command
+    target: ~/   # location to symlink this feature to
+
+  - slug: mac
+    enabled: macos
+    target: ~/
+
+  - slug: mac-opt
+    enabled: macos
+    target: /opt/
+
+  - slug: linux
+    enabled: linux
+    target: ~/
+
+  - slug: custom
+    # custom enabled commands have to be tagged with !command
+    # the specified command needs to return exit code 0 to count as enabled
+    enabled: !command /some/custom/script
+    target: ~/
+    
+  - slug: linux_wayland
+    target: ~/
+    enabled: !command /bin/bash -c "if [[ $XDG_SESSION_TYPE -ne wayland ]] ; then exit 1 ; fi"
 ```
 
-Any directories whose name matches the format `{slug,slug,...}<any name>` get symlinked to the specified target.
+The content of directories matching the format `{slug,slug,...}<name>`, where at least one enabled feature
+matches a specified slug, gets symlinked to the target specified in the feature.
 
-**If multiple features are assigned the highest one in the config file is used.**
+**If multiple features are assigned, priority is determined by their order in the config file. (top - higher priority, bottom - lower priority)**
 
 ## Caveats
 
 While other symlink farms like GNU stow perform "tree folding" to figure out where symlinking is most efficient,
-clink only symlinks files, creating non-existing parent directories in the process. To avoid leaving
-empty "orphan" folders after unlinking, clink removes empty directories up until, but not including, the
-original target. This behaviour can be overwritten by specifying the --leave-orphans flag with unlink.
+clink only symlinks files, creating non-existing parent directories in the process. This is somewhat mitigated
+by the default unlink behaviour, where clink removes all empty parent folders of a link, up until the target itself.
+
+You can disable this by adding the `-l (--leave-orphans)` flag to unlink.

clink.example.yaml

@@ -0,0 +1,20 @@
+features:
+  - slug: all
+    target: ~/.config
+    enabled: all
+
+  - slug: mac
+    target: ~/.config
+    enabled: macos
+
+  - slug: mac_home
+    target: ~/
+    enabled: macos
+
+  - slug: linux
+    target: ~/.config
+    enabled: linux
+
+  - slug: linux_wayland
+    target: ~/
+    enabled: !command /bin/bash -c "if [[ $XDG_SESSION_TYPE -ne wayland ]] ; then exit 1 ; fi"