Add more documentation to the sample config

Author: fd0

doc/grobi.conf

@@ -1,29 +1,89 @@
 # vim:ft=yaml
 
+# The commands listed in execute_after will be run after an output
+# configuration was changed.
 execute_after:
   - setxkbmap dvorak
 
+# These are the rules grobi tries to match to the current output configuration.
+# The rules are evaluated top to bottom, the first matching rule is applied and
+# processing stops.
+#
+# The rules belowe are written for a typical Laptop in mind, which hase several
+# external connectors (HDMI2, HDMI3) in addition to the internal display
+# (LVDS1). It may even be placed in a Docking Station, which adds more outputs
+# that aren't present outside it.
 rules:
+
+  # This is a rule for a docking station.
   - name: Docking Station
+    # grobi takes the list of all the
+    # outputs xrandr returns and verifies that HDMI2 and HDMI3 are connected, and
+    # DP2-2 is present (but may be disconnected).
     outputs_connected: [HDMI2, HDMI3]
     outputs_present: [DP2-2]
+
+    # when this rule matches, HDMI2 and HDMI3 are activated in their default
+    # resolution and set besides each other in a typical dual-monitor
+    # configuration: left is HDMI2, right is HDMI3
     configure_row:
         - HDMI2
         - HDMI3
+
+    # atomic instructs grobi to only call xrandr once and configure all the
+    # outputs. This does not always work with all graphic cards.
     atomic: true
+
+    # For the output HDMI3, the flag --primary will be added to the xrandr
+    # call, so that e.g. the tray icons are displayed on this monitor (requires
+    # the window manager to do this).
     primary: HDMI3
 
+    # Additional commands can be specified per rule, in this case we make sure
+    # that xautolock is enabled and locks the screen after a while.
+    execute_after:
+      - xautolock -enable
+
+
+  # This is a rule for mobile computing, i.e. outside of the docking station defined above.
   - name: Mobile
+
+    # In order to match, the outputs HDMI2 and HDMI3 may be present, but must be disconnected.
     outputs_disconnected:
       - HDMI2
       - HDMI3
+
+    # Here, only the internal LCD panel is activated.
     configure_single: LVDS1
 
+    execute_after:
+      - xautolock -enable
+
+
+  # This is a rule for giving a presentation.
   - name: VGA Projector
-    outputs_connected: [LVDS1, VGA1]
+
+    # This rule requires that a display is connected to the VGA port.
+    outputs_connected: [VGA1]
+
+    # And it also requires that none of the outputs called DP2-? are present,
+    # this way we can test that the Laptop is not in the Docking Station.
     outputs_absent: [DP2-?]
+
+    # Two displays are enabled side by side: LVDS1 on the left with the default
+    # resolution, and VGA1 at the resolution 1024x768 (which hopefully works
+    # for all projectors).
     configure_row:
       - LVDS1
       - VGA1@1024x768
+
+    # The following command makes sure that xautolock won't lock the screen
+    # during the presentation.
     execute_after:
-      - pkill xautolock
+      - xautolock -disable
+
+  # If none of the rules above match, it's a good idea to have a fallback rule
+  # which enables an output device that is always present, so you can debug
+  # what's going on.
+  - name: Fallback
+    configure_single: eDP1