Add documentation for DynamicStrings.

1 files changed, 77 insertions, 32 deletions

diff --git a/readme.md b/readme.md
index 2ddfb41..cb3b9cc 100644
--- a/readme.md
+++ b/readme.md
@@ -542,6 +542,23 @@ Monitors have default aliases.  The sections below describe every
 monitor in turn, but before we provide a list of the configuration
 options (or *monitor arguments*) they all share.
 
+### Dynamic Strings
+
+Some monitors allow usage of strings that depend on some integer value
+from 0 to 8 by replacing all occurences of `"%%"` with it
+(i.e. `"<icon=/path/to/icon_%%.xpm/>"` will be interpreted
+as `"<icon=/path/to/icon_3.xpm/>"` when the value is `3`, also `"%"` is interpreted
+as `"%"`, `"%%"` as `"3"`, `"%%%"` as `"3%"`, `"%%%%"` as `"33"` and so on). Essentially
+it allows to replace vertical bars with custom icons. For example,
+
+    Run Brightness
+      [ "-t", "<dstr>"
+      , "--"
+      , "--brightness-dynamic-string", "<icon=bright_%%.xpm/>"
+      ] 30
+
+Will display `bright_0.xpm` to `bright_8.xpm` depending on current brightness
+value.
 
 ### Default Monitor Arguments
 
@@ -693,33 +710,38 @@ something like:
 
 - Aliases to the interface name: so `Network "eth0" []` can be used as
   `%eth0%`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+  - `--rx-dynamic-string`: dynamic string for reception rate in `rxdstr`.
+  - `--tx-dynamic-string`: dynamic string for transmission rate in `txdstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-  `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `txbar`, `txvbar`. Reception
-  and transmission rates (`rx` and `tx`) are displayed by default as
-  Kb/s, without any suffixes, but you can set the `-S` to "True" to
-  make them displayed with adaptive units (Kb/s, Mb/s, etc.).
+  `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `rxdstr`, `txbar`, `txvbar`,
+  `txdstr`. Reception and transmission rates (`rx` and `tx`) are displayed
+  by default as Kb/s, without any suffixes, but you can set the `-S` to
+  "True" to make them displayed with adaptive units (Kb/s, Mb/s, etc.).
 - Default template: `<dev>: <rx>KB|<tx>KB`
 
 ### `DynNetwork Args RefreshRate`
 
 - Active interface is detected automatically
 - Aliases to "dynnetwork"
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+  - `--rx-dynamic-string`: dynamic string for reception rate in `rxdstr`.
+  - `--tx-dynamic-string`: dynamic string for transmission rate in `txdstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-  `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `txbar`, `txvbar`. Reception and
-  transmission rates (`rx` and `tx`) are displayed in Kbytes per second,
-  and you can set the `-S` to "True" to make them displayed with units (the
-  string "Kb/s").
+  `dev`, `rx`, `tx`, `rxbar`, `rxvbar`, `rxdstr`, `txbar`, `txvbar`,
+  `txdstr`. Reception and transmission rates (`rx` and `tx`) are displayed
+  in Kbytes per second, and you can set the `-S` to "True" to make them
+  displayed with units (the string "Kb/s").
 - Default template: `<dev>: <rx>KB|<tx>KB`
 
 ### `Wireless Interface Args RefreshRate`
 
 - Aliases to the interface name with the suffix "wi": thus, `Wireless
   "wlan0" []` can be used as `%wlan0wi%`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+  - `--quality-dynamic-string`: dynamic string for connection quality in `qualitydstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-            `essid`, `quality`, `qualitybar`, `qualityvbar`
+            `essid`, `quality`, `qualitybar`, `qualityvbar`, `qualitydstr`
 - Default template: `<essid> <quality>`
 - Requires the C library [iwlib] (part of the wireless tools suite)
   installed in your system. In addition, to activate this plugin you
@@ -728,10 +750,13 @@ something like:
 ### `Memory Args RefreshRate`
 
 - Aliases to `memory`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+  - `--used-dynamic-string`: dynamic string for used memory ratio in `useddstr`.
+  - `--free-dynamic-string`: dynamic string for free memory ratio in `freedstr`.
 - Variables that can be used with the `-t`/`--template` argument:
              `total`, `free`, `buffer`, `cache`, `rest`, `used`,
-             `usedratio`, `usedbar`, `usedvbar`, `freeratio`, `freebar`, `freevbar`
+             `usedratio`, `usedbar`, `usedvbar`, `useddstr`,
+             `freeratio`, `freebar`, `freevbar`, `freedstr`
 - Default template: `Mem: <usedratio>% (<cache>M)`
 
 ### `Swap Args RefreshRate`
@@ -745,19 +770,24 @@ something like:
 ### `Cpu Args RefreshRate`
 
 - Aliases to `cpu`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+  - `--load-dynamic-string`: dynamic string for cpu load in `dstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-	    `total`, `bar`, `vbar`, `user`, `nice`, `system`, `idle`, `iowait`
+	    `total`, `bar`, `vbar`, `dstr`, `user`, `nice`, `system`, `idle`, `iowait`
 - Default template: `Cpu: <total>%`
 
 ### `MultiCpu Args RefreshRate`
 
 - Aliases to `multicpu`
-- Args: default monitor arguments
+- Args: default monitor arguments, plus:
+  - `--load-dynamic-string`: dynamic string for overall cpu load in `dstr`.
+  - `--load-dynamic-strings`: dynamic string for each cpu load in `autodstr`, `dstr{i}`.
+                              This option can be specified several times. nth option
+                              corresponds to nth cpu.
 - Variables that can be used with the `-t`/`--template` argument:
-	    `autototal`, `autobar`, `autovbar`, `autouser`, `autonice`,
-	    `autosystem`, `autoidle`, `total`, `bar`, `vbar`, `user`, `nice`,
-	    `system`, `idle`, `total0`, `bar0`, `vbar0`, `user0`, `nice0`,
+	    `autototal`, `autobar`, `autovbar`, `autodstr`, `autouser`, `autonice`,
+	    `autosystem`, `autoidle`, `total`, `bar`, `vbar`, `dstr`, `user`, `nice`,
+	    `system`, `idle`, `total0`, `bar0`, `vbar0`, `dstr0`, `user0`, `nice0`,
 	    `system0`, `idle0`, ...
   The auto* variables automatically detect the number of CPUs on the system
   and display one entry for each.
@@ -788,9 +818,15 @@ something like:
   - `-p`: color to display positive power (battery charging)
   - `-f`: file in `/sys/class/power_supply` with AC info (default:
     "AC/online")
+  - `--on-dynamic-string`: dynamic string for current battery charge
+    when AC is "on" in `leftdstr`.
+  - `--off-dynamic-string`: dynamic string for current battery charge
+    when AC is "off" in `leftdstr`.
+  - `--idle-dynamic-string`: dynamic string for current battery charge
+    when AC is "idle" in `leftdstr`.
 
 - Variables that can be used with the `-t`/`--template` argument:
-	    `left`, `leftbar`, `leftvbar`, `timeleft`, `watts`, `acstatus`
+	    `left`, `leftbar`, `leftvbar`, `leftdstr`, `timeleft`, `watts`, `acstatus`
 - Default template: `Batt: <watts>, <left>% / <timeleft>`
 - Example (note that you need "--" to separate regular monitor options from
   Battery's specific ones):
@@ -863,10 +899,12 @@ more than one battery.
 - Aliases to `disku`
 - Disks: list of pairs of the form (device or mount point, template),
   where the template can contain `<size>`, `<free>`, `<used>`, `<freep>` or
-  `<usedp>`, `<freebar>`, `<freevbar>`, `<usedbar>` or `<usedvbar>` for total,
-  free, used, free percentage and used percentage of the given file system
-  capacity.
-- Args: default monitor arguments. `-t`/`--template` is ignored.
+  `<usedp>`, `<freebar>`, `<freevbar>`, `<freedstr>`, `<usedbar>`,
+  `<usedvbar>` or `<useddstr>` for total, free, used, free percentage and
+  used percentage of the given file system capacity.
+- Args: default monitor arguments. `-t`/`--template` is ignored. Plus
+  - `--free-dynamic-string`: dynamic string for free disk space in `freedstr`.
+  - `--used-dynamic-string`: dynamic string for used disk space in `useddstr`.
 - Default template: none (you must specify a template for each file system).
 - Example:
 
@@ -880,9 +918,13 @@ more than one battery.
 - Disks: list of pairs of the form (device or mount point, template),
   where the template can contain `<total>`, `<read>`, `<write>` for total,
   read and write speed, respectively. There are also bar versions of each:
-  `<totalbar>`, `<totalvbar>`, `<readbar>`, `<readvbar>`, `<writebar>`, and
-  `<writevbar>`.
-- Args: default monitor arguments. `-t`/`--template` is ignored.
+  `<totalbar>`, `<totalvbar>`, `<totaldstr>`,
+  `<readbar>`, `<readvbar>`, `<readdstr>`,
+  `<writebar>`, `<writevbar>`, and `<writedstr>`.
+- Args: default monitor arguments. `-t`/`--template` is ignored. Plus
+  - `--total-dynamic-string`: dynamic string for total disk I/O in `<totaldstr>`.
+  - `--write-dynamic-string`: dynamic string for write disk I/O in `<writedstr>`.
+  - `--read-dynamic-string`: dynamic string for read disk I/O in `<readdstr>`.
 - Default template: none (you must specify a template for each file system).
 - Example:
 
@@ -970,8 +1012,9 @@ more than one battery.
         - Long option: `--offc`
     - `--highd` _number_ High threshold for dB. Defaults to -5.0.
     - `--lowd` _number_ Low threshold for dB. Defaults to -30.0.
+    - `--volume-dynamic-string` _string_ dynamic string for current volume in `volumedstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-            `volume`, `volumebar`, `volumevbar`, `dB`, `status`
+            `volume`, `volumebar`, `volumevbar`, `volumedstr`, `dB`, `status`
 - Note that `dB` might only return 0 on your system. This is known
   to happen on systems with a pulseaudio backend.
 - Default template: `Vol: <volume>% <status>`
@@ -988,9 +1031,10 @@ more than one battery.
   `-P`, `-S` and `-Z`, with an string argument, to represent the
   playing, stopped and paused states in the `statei` template field.
   The environment variables `MPD_HOST` and `MPD_PORT` are used to configure the
-  mpd server to communicate with.
+  mpd server to communicate with. Also available:
+  - `lapsed-dynamic-string`: dynamic string for current track position in `dstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-             `bar`, `vbar`, `state`, `statei`, `volume`, `length`,
+             `bar`, `vbar`, `dstr`, `state`, `statei`, `volume`, `length`,
              `lapsed`, `remaining`,
              `plength` (playlist length), `ppos` (playlist position),
              `name`, `artist`, `composer`, `performer`,
@@ -1110,8 +1154,9 @@ more than one battery.
        actual_brightness)
     - `-M`: file with the maximum brightness (default:
        max_brightness)
+    - `--brightness-dynamic-string`: dynamic string for current brightness in `dstr`.
 - Variables that can be used with the `-t`/`--template` argument:
-	    `vbar`, `percent`, `bar`
+	    `vbar`, `percent`, `bar`, `dstr`
 - Default template: `<percent>`
 - Example: