doc: updated readme

README.md

@@ -19,34 +19,83 @@ set -wg window-status-current-format "#I:#W#F [$WINDOW_LOAD]"
 
 > [!TIP]
 > I haven't really found tmux to be very good at garbage-collecting the processes it spawns
-> per-window, so I actually recommend adding for example `-t 10` to limit the duration of the
+> per-window, so I actually recommend adding for example `-t 60` to limit the duration of the
 > monitor command. It appears that tmux will promptly re-spawn a process that exited, so it
 > shouldn't be noticeable and will spare some zombie processes.
 
 ## Usage
 
 ```
+A CPU load monitor of process trees
+
 Usage: pidtree_mon [OPTIONS] <pid>...
 
 Arguments:
-  <pid>...
+  <pid>...  The collection of PIDs to monitor
 
 Options:
-  -t, --timeout <TIMEOUT>
-  -f, --field <field>      sum | all_loads | if_greater:value:then[:else] [default: sum all_loads]
-  -h, --help               Print help
-  -V, --version            Print version
+  -t, --timeout <TIMEOUT>      The maximum time to collect statistics
+  -f, --field <field>          sum[_t][:FMT] | all_loads[_t][:FMT] | TEST
+                               FMT := .N | %N | TEST
+                               TEST := if_range:[L]..[H]:then[:else] | if_greater:thr:then[:else]
+                                [default: sum all_loads]
+  -s, --separator <SEPARATOR>  The field separator [default: " "]
+  -h, --help                   Print help
+  -V, --version                Print version
+
+Explanation of fields
+
+Multiple fields can be passed via -f/--field. A basic field can be:
+ * `sum' - sum of loads of all provided process trees,
+ * `all_loads' - produces multiple fields, one for each process tree.
+
+The values are scaled per-core, so n means n whole cores are being used.
+Adding `_t' to either field scales the loads according to the total computing power,
+1 being the maximum.
+
+A format specifier can be added after colon:
+ * .N - prints with N digits after decimal point,
+ * %N - prints with N digits after decimal point, scaled up by a factor of 100,
+ * if_range:[L]..[H]:then[:else] - produces `then` if field value is between `L' and `H',
+                                   `else` otherwise, `L`, `H` and `else` are optional,
+ * if_greater:thr:then[:else]    - like if_range, but field value must be greater than `thr`,
+                                   DEPRECATED
+
+Additionally, the last two specifiers can be used alone, without a preceding value,
+in this case, the value defaults to `sum`.
 ```
 
-The specified fields are printed space-separated in each line. Each line represents one measurement.
-Available fields:
+## Examples
+
+### print load status using different characters
+```sh
+pidtree_mon -s '' \
+    -f 'sum:if_range:0.4..1.5: ' \
+    -f 'sum:if_range:1.5..:🔥' \
+    <pids>
+```
 
-| field                          | description                                                   |
-| :----------------------------- | :------------------------------------------------------------ |
-| `sum`                          | sum of CPU loads for all subtrees rooted in passed `<pid>...` |
-| `all_loads`                    | loads of each subtree, separated by space                     |
-| `if_greater:value:then[:else]` | `then` if `sum` > `value`, `else` otherwise                   |
+Here we use per-core loads, mainly to detect potential single-core tight-loops in a session
+(40%..150% range). Above 150%, the more serious emoji is used.
+
+### print whole system's load as a vertical bar
+```sh
+    pidtree_mon
+        -s '' \
+        -f 'sum_t:if_range:0.000..0.050: ' \
+        -f 'sum_t:if_range:0.050..0.125:#[fg=#B2E0B2]▁' \
+        -f 'sum_t:if_range:0.125..0.250:#[fg=#A3D6A3]▂' \
+        -f 'sum_t:if_range:0.250..0.375:#[fg=#94CC94]▃' \
+        -f 'sum_t:if_range:0.375..0.500:#[fg=#85C285]▄' \
+        -f 'sum_t:if_range:0.500..0.625:#[fg=#FFD6A0]▅' \
+        -f 'sum_t:if_range:0.625..0.750:#[fg=#FFB3A0]▆' \
+        -f 'sum_t:if_range:0.750..0.875:#[fg=#FF8C94]▇' \
+        -f 'sum_t:if_range:0.875..1.500:#[fg=#FF6F61]█' \
+        1 \
+```
 
+This command can be used directly in tmux with `#()`. It uses the total processor usage by PID 1,
+which is not ideal, but will be good enough most of the time.
 
 ## Why?
 
@@ -99,7 +148,7 @@ The exact counterpart of the above configuration using `pidtree_mon` would be:
 ```sh
 %hidden WINDOW_FIRE="#[fg=red]#(\
         pidtree_mon \
-            -t 10 \
+            -t 60 \
             -f 'if_greater:0.5:::' \
             \$(tmux list-panes -t #{window_id} -F '##{pane_pid}') \
 )#[fg=black]"