Update docs

examples/nav-layer.conf

@@ -1,29 +1,65 @@
+# Goal:
+#
+# To create a vi like navigation layer accessible by holding capslock while having capslock
+# otherwise behave like the control key (when held) and escape when tapped.
+#
+# In essence we want:
+#
+#  - capslock+h = left
+#  - capslock+j = down
+#  - capslock+k = up
+#  - capslock+l = right
+#
+#  - capslock+shift+h = C-left
+#  - capslock+shift+l = C-right
+#  - capslock+shift+j = C-down
+#  - capslock+shift+k = C-up
+#
+#  - capslock = escape (when tapped)
+#
+# In all other instances capslock should behave as normal control:
+#
+#  - capslock+a = C-a
+#  - capslock+b = C-b
+#  - capslock+c = C-c
+#  ...
+#  - capslock+shift+i = C-S-i
+#  - capslock+shift+k = C-S-k
+#  ....
+
+# This is achieved by creating a 'nested layer' called [capslock_shift]
+# which is activated whenever capslock and shift are simultaneously
+# held.
+#
+# The important bindings are:
+#
+# [shift]
+# capslock = layer(capslock_shift)
+#
+# [capslock]
+# shift = layer(capslock_shift)
+
 [ids]
 
 *
 
 [main]
 
-# activate [capslock] when held and escape when pressed
 capslock = overload(capslock, esc)
 
+# The default shift layer (the layer activated when shift is pressed).
 [shift]
 
-# causes shift+capslock (in that order) to activate [capslock_shift]
 capslock = layer(capslock_shift)
 
-# [capslock] will behave as (real/stackable) control in all instances except
-# hjkl in which case it will behave as the arrow keys.
 [capslock:C]
 
-# Causes capslock+shift (in that order) to activate [capslock_shift]
 shift = layer(capslock_shift)
 h = left
 j = down
 k = up
 l = right
 
-# nested layer accessible with capslock+shift or shift+capslock
 [capslock_shift]
 
 h = C-left