doc/yambar-modules: document the ‘script’ module

doc/yambar-modules.5.scd

@@ -714,11 +714,107 @@ bar:
               true:
                 string:
                   margin: 5
-                  text: "{id}: {state}"```
+                  text: "{id}: {state}"
+```
+
+# SCRIPT
+
+This module executes a user-provided script (or binary!) that writes
+tags on its stdout.
+
+The script can either exit immediately after writing a set of tags, in
+which case yambar will display those tags until yambar is
+terminated. Or, the script can continue executing and update yambar
+with new tag sets, either periodically, or when there is new data to
+feed to yambar.
+
+Tag sets, or _transactions_, are separated by an empty line. Each
+_tag_ is a single line on the format:
+
+```
+name|type|value
+```
+
+Where _name_ is what you also use to refer to the tag in the yambar
+configuration, _type_ is one of the tag types defined in
+*yambar-tags*(5), and _value_ is the tag’s value.
+
+Example:
+
+```
+var1|string|hello
+var2|int|13
+
+var1|string|world
+var2|int|37
+```
+
+The example above consists of two transactions. Each transaction has
+two tags: one string tag and one integer tag. The second transaction
+replaces the tags from the first transaction.
+
+Supported _types_ are:
+
+- string
+- int
+- bool
+- float
+- range:n-m (e.g. *var|range:0-100|57*)
+
+## TAGS
+
+User defined.
+
+## CONFIGURATION
+
+[[ *Name*
+:[ *Type*
+:[ *Req*
+:[ *Description*
+|  path
+:  string
+:  yes
+:  Path to script/binary to execute. Must be an absolute path.
+|  args
+:  list of strings
+:  no
+:  Arguments to pass to the script/binary.
+
+## EXAMPLES
+
+Here is an "hello world" example script:
+
+```
+#!/bin/sh
+
+while true; do
+    echo "test|string|hello"
+    echo ""
+    sleep 3
+
+    echo "test|string|world"
+    echo ""
+    sleep 3
+done
+```
+
+This script will emit a single string tag, _test_, and alternate its
+value between *hello* and *world* every three seconds.
+
+A corresponding yambar configuration could look like this:
+
+```
+bar:
+  left:
+    - script:
+        path: /path/to/script.sh
+        args: []
+        content: {string: {text: "{test}"}}
+```
 
 # SWAY-XKB
 
-This module uses *Sway* extenions to the I3 IPC API to monitor input
+This module uses *Sway* extensions to the I3 IPC API to monitor input
 devices' active XKB layout. As such, it requires Sway to be running.
 
 *Note* that the _content_ configuration option is a *template*;