doc: i3

doc/f00bar-modules.5.scd

@@ -111,7 +111,7 @@ _/sys/class/backlight_, and uses *udev* to monitor for changes.
 |  name
 :  string
 :  yes
-:  The backlight device's name (one of the names in _/sys/class/backlight_)
+:  The backlight device's name (one of the names in */sys/class/backlight*)
 
 ## EXAMPLES
 
@@ -163,7 +163,7 @@ uses *udev* to monitor for changes.
 |  name
 :  string
 :  yes
-:  Battery device name (one of the names in _/sys/class/power_supply_)
+:  Battery device name (one of the names in */sys/class/power_supply*)
 |  poll-interval
 :  int
 :  no
@@ -223,6 +223,93 @@ bar:
           string: {text: "{date} {time}"}
 ```
 
+# I3 (and Sway)
+
+This module monitors i3 and sway workspaces.
+
+Unlike other modules where the _content_ attribute is just a single
+*particle*, the i3 module's _content_ is an associative array mapping
+i3/sway workspace names to a particle.
+
+You can specify a default particle to use with an empty workspace
+name, *""*.
+
+It also recognizes the special name *current*, which always represents
+the currently focused workspace.
+
+## TAGS
+
+[[ *Name*
+:[ *Type*
+:[ *Description*
+|  name
+:  string
+:  The workspace name
+|  visible
+:  bool
+:  True if the workspace is currently visible (on any output)
+|  focused
+:  bool
+:  True if the workspace is currently focused
+|  urgent
+:  bool
+:  True if the workspace has the urgent flag set
+|  state
+:  string
+:  One of *urgent*, *focused*, *unfocused* or *invisible* (note:
+   *unfocused* is when it is visible, but neither focused nor urgent).
+|  application
+:  string
+:  Name of application currently focused on this workspace
+|  title
+:  string
+:  This workspace's focused window's title
+
+## CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  content
+:  associative array
+:  yes
+:  Unlike other modules, _content_ is an associative array mapping
+   workspace names to particles. Use *""* to specify a default
+   fallback particle, or *current* for the currently active workspace.
+|  left-spacing
+:  int
+:  no
+:  Space, in pixels, on the left-side of each rendered workspace particle
+|  right-spacing
+:  int
+:  no
+:  Space, in pixels, on the right-side of each rendered workspace particle
+|  spacing
+:  int
+:  no
+:  Short-hand for setting both _left-spacing_ and _right-spacing_
+
+## EXAMPLES
+
+This renders all workspace names, with an *\** indicating the
+currently focused one. It also renders the currently focused
+application name and window title.
+
+```
+bar:
+  left:
+    - i3:
+        content:
+          "":
+            map:
+              tag: state
+              default: {string: {text: "{name}"}}
+              values:
+                focused: {string: {text: "{name}*"}}
+          current: { string: {text: "{application}: {title}"}}
+```
+
 # SEE ALSO
 
 *f00bar-particles*(5), *f00bar-tags*(5), *f00bar-decorations*(5)