Subdivide system monitors

1 files changed, 813 insertions, 835 deletions

diff --git a/doc/plugins.org b/doc/plugins.org
index 0516b67..4c6b2aa 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -1,5 +1,3 @@
-#+OPTIONS: toc:t
-
 * System Monitor Plugins
 
 This is the description of the system monitor plugins available in
@@ -33,7 +31,7 @@ then specifies the battery-specific =off= option.
     100
 #+end_src
 
-** Icon patterns
+** Icon Patterns
 
 Some monitors allow usage of strings that depend on some integer value
 from 0 to 8 by replacing all occurrences of =%%= with it
@@ -228,1036 +226,1016 @@ something like:
   Glasgow Airport: 16.0C
 #+end_src
 
-** =Uptime Args RefreshRate=
-
-- Aliases to =uptime=
-- Args: default monitor arguments. The low and high thresholds refer to
-  the number of days.
-- Variables that can be used with the =-t/--template= argument: =days=,
-  =hours=, =minutes=, =seconds=. The total uptime is the sum of all
-  those fields. You can set the =-S= argument to =True= to add units to
-  the display of those numeric fields.
-- Default template: =Up: <days>d <hours>h <minutes>m=
-
-** =Weather StationID Args RefreshRate=
-
-- Aliases to the Station ID: so =Weather "LIPB" []= can be used in
-  template as =%LIPB%=
-- Thresholds refer to temperature in the selected units
-- Args: default monitor arguments, plus:
-
-  - =--weathers= /string/ : display a default string when the =weather=
-    variable is not reported.
-
-    - short option: =-w=
-    - Default: ""
-
-  - =--useManager= /bool/ : Whether to use one single manager per
-    monitor for managing network connections or create a new one every
-    time a connection is made.
-
-    - Short option: =-m=
-    - Default: True
-
-- Variables that can be used with the =-t/--template= argument:
-  =station=, =stationState=, =year=, =month=, =day=, =hour=,
-  =windCardinal=, =windAzimuth=, =windMph=, =windKnots=, =windMs=,
-  =windKmh= =visibility=, =skyCondition=, =weather=, =tempC=, =tempF=,
-  =dewPointC=, =dewPointF=, =rh=, =pressure=
-- Default template: =<station>: <tempC>C, rh <rh>% (<hour>)=
-- Retrieves weather information from http://tgftp.nws.noaa.gov. Here is
-  an [[https://tgftp.nws.noaa.gov/data/observations/metar/decoded/CYLD.TXT][example]], also showcasing the kind of information that may be
-  extracted.
-
-** =WeatherX StationID SkyConditions Args RefreshRate=
-
-- Works in the same way as =Weather=, but takes an additional argument,
-  a list of pairs from sky conditions to their replacement (typically a
-  unicode string or an icon specification).
-- Use the variable =skyConditionS= to display the replacement of the
-  corresponding sky condition. All other =Weather= template variables
-  are available as well.
-
-For example:
-
-#+begin_src haskell
-  WeatherX "LEBL"
-           [ ("clear", "🌣")
-           , ("sunny", "🌣")
-           , ("mostly clear", "🌤")
-           , ("mostly sunny", "🌤")
-           , ("partly sunny", "⛅")
-           , ("fair", "🌑")
-           , ("cloudy","☁")
-           , ("overcast","☁")
-           , ("partly cloudy", "⛅")
-           , ("mostly cloudy", "🌧")
-           , ("considerable cloudiness", "⛈")]
-           ["-t", "<fn=2><skyConditionS></fn> <tempC>° <rh>%  <windKmh> (<hour>)"
-           , "-L","10", "-H", "25", "--normal", "black"
-           , "--high", "lightgoldenrod4", "--low", "darkseagreen4"]
-           18000
-#+end_src
-
-As mentioned, the replacement string can also be an icon specification,
-such as =("clear", "<icon=weather-clear.xbm/>")=.
-
-** =Network Interface Args RefreshRate=
-
-- Aliases to the interface name: so =Network "eth0" []= can be used as
-  =%eth0%=
-- Thresholds refer to velocities expressed in Kb/s
-- Args: default monitor arguments, plus:
-
-  - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=.
-  - =--tx-icon-pattern=: dynamic string for transmission rate in
-    =txipat=.
-  - =--up=: string used for the =up= variable value when the interface
-    is up.
-
-- Variables that can be used with the =-t=/=--template= argument: =dev=,
-  =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=, =txipat=,
-  =up=. 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"
-- Thresholds are expressed in Kb/s
-- Args: default monitor arguments, plus:
-
-- =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=.
-- =--tx-icon-pattern=: dynamic string for transmission rate in =txipat=
-- =--devices=: comma-separated list of devices to show.
-
-- Variables that can be used with the =-t=/=--template= argument:
-  =dev=, =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=,
-  =txipat=.
-
-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=
-- Example of usage of =--devices= option:
-
-    =["--", "--devices", "wlp2s0,enp0s20f41"]=
-
-** =Wireless Interface Args RefreshRate=
-
-- If set to "", first suitable wireless interface is used.
-- Aliases to the interface name with the suffix "wi": thus,
-  =Wireless   "wlan0" []= can be used as =%wlan0wi%=, and
-  =Wireless "" []= as =%wi%=.
-- Args: default monitor arguments, plus:
-
-  - =--quality-icon-pattern=: dynamic string for connection quality in
-    =qualityipat=.
-
-- Variables that can be used with the =-t=/=--template= argument:
-  =ssid=, =signal=, =quality=, =qualitybar=, =qualityvbar=,
-  =qualityipat=
-- Thresholds refer to link quality on a =[0, 100]= scale. Note that
-  =quality= is calculated from =signal= (in dBm) by a possibly lossy
-  conversion. It is also not taking into account many factors such as
-  noise level, air busy time, transcievers' capabilities and the others
-  which can have drastic impact on the link performance.
-- Default template: =<ssid> <quality>=
-- To activate this plugin you must pass the =with_nl80211= or the
-  =with_iwlib= flag during compilation.
-
-** =Memory Args RefreshRate=
-
-- Aliases to =memory=
-- Args: default monitor arguments, plus:
-
-  - =--used-icon-pattern=: dynamic string for used memory ratio in
-    =usedipat=.
-  - =--free-icon-pattern=: dynamic string for free memory ratio in
-    =freeipat=.
-  - =--available-icon-pattern=: dynamic string for available memory
-    ratio in =availableipat=.
-
-- Thresholds refer to percentage of used memory
-- Variables that can be used with the =-t/--template= argument:
-  =total=, =free=, =buffer=, =cache=, =available=, =used=, =usedratio=,
-  =usedbar=, =usedvbar=, =usedipat=, =freeratio=, =freebar=, =freevbar=,
-  =freeipat=, =availableratio=, =availablebar=, =availablevbar=,
-  =availableipat=
-- Default template: =Mem: <usedratio>% (<cache>M)=
-
-** =Swap Args RefreshRate=
-
-- Aliases to =swap=
-- Args: default monitor arguments
-- Thresholds refer to percentage of used swap
-- Variables that can be used with the =-t/--template= argument:
-  =total=, =used=, =free=, =usedratio=
-- Default template: =Swap: <usedratio>%=
-
-** =Cpu Args RefreshRate=
-
-- Aliases to =cpu=
-- Args: default monitor arguments, plus:
-
-  - =--load-icon-pattern=: dynamic string for cpu load in =ipat=
-
-- Thresholds refer to percentage of CPU load
-- Variables that can be used with the =-t/--template= argument:
-  =total=, =bar=, =vbar=, =ipat=, =user=, =nice=, =system=, =idle=,
-  =iowait=
-- Default template: =Cpu: <total>%=
-
-** =MultiCpu Args RefreshRate=
-
-- Aliases to =multicpu=
-- Args: default monitor arguments, plus:
-
-  - =--load-icon-pattern=: dynamic string for overall cpu load in
-    =ipat=.
-  - =--load-icon-patterns=: dynamic string for each cpu load in
-    =autoipat=, =ipat{i}=. This option can be specified several times.
-    nth option corresponds to nth cpu.
-  - =--fallback-icon-pattern=: dynamic string used by =autoipat= and
-    =ipat{i}= when no =--load-icon-patterns= has been provided for
-    =cpu{i}=
-  - =--contiguous-icons=: flag (no value needs to be provided) that
-    causes the load icons to be drawn without padding.
-
-- Thresholds refer to percentage of CPU load
-- Variables that can be used with the =-t/--template= argument:
-  =autototal=, =autobar=, =autovbar=, =autoipat=, =autouser=,
-  =autonice=, =autosystem=, =autoidle=, =total=, =bar=, =vbar=, =ipat=,
-  =user=, =nice=, =system=, =idle=, =total0=, =bar0=, =vbar0=, =ipat0=,
-  =user0=, =nice0=, =system0=, =idle0=, ... The auto* variables
-  automatically detect the number of CPUs on the system and display one
-  entry for each.
-- Default template: =Cpu: <total>%=
-
-** =Battery Args RefreshRate=
-
-- Same as
-
-  #+begin_src haskell
-    BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate
-  #+end_src
-
-** =BatteryP Dirs Args RefreshRate=
-
-- Aliases to =battery=
-
-- Dirs: list of directories in =/sys/class/power_supply/= where to look
-  for the ACPI files of each battery. Example: =["BAT0","BAT1","BAT2"]=.
-  Only up to 3 existing directories will be searched.
-
-- Args: default monitor arguments, plus the following specific ones
-  (these options, being specific to the monitor, are to be specified
-  after a =--= in the argument list):
-
-  - =-O=: string for AC "on" status (default: "On")
-  - =-i=: string for AC "idle" status (default: "On")
-  - =-o=: string for AC "off" status (default: "Off")
-  - =-L=: low power (=watts=) threshold (default: 10)
-  - =-H=: high power threshold (default: 12)
-  - =-l=: color to display power lower than the =-L= threshold
-  - =-m=: color to display power lower than the =-H= threshold
-  - =-h=: color to display power higher than the =-H= threshold
-  - =-p=: color to display positive power (battery charging)
-  - =-f=: file in =/sys/class/power_supply= with AC info (default:
-    "AC/online")
-  - =-A=: a number between 0 and 100, threshold below which the action
-    given by =-a=, if any, is performed (default: 5)
-  - =-a=: a string with a system command that is run when the percentage
-    left in the battery is less or equal than the threshold given by the
-    =-A= option. If not present, no action is undertaken.
-  - =-P=: to include a percentage symbol in =left=.
-  - =--on-icon-pattern=: dynamic string for current battery charge when
-    AC is "on" in =leftipat=.
-  - =--off-icon-pattern=: dynamic string for current battery charge when
-    AC is "off" in =leftipat=.
-  - =--idle-icon-pattern=: dynamic string for current battery charge
-    when AC is "idle" in =leftipat=.
-  - =--lows=: string for AC "off" status and power lower than the =-L=
-    threshold (default: "")
-  - =--mediums=: string for AC "off" status and power lower than the
-    =-H= threshold (default: "")
-  - =--highs=: string for AC "off" status and power higher than the =-H=
-    threshold (default: "")
-
-- Variables that can be used with the =-t/--template= argument:
-  =left=, =leftbar=, =leftvbar=, =leftipat=, =timeleft=, =watts=,
-  =acstatus=
-
-- Default template: =Batt: <watts>, <left>% / <timeleft>=
-
-- Example (note that you need "--" to separate regular monitor options
-  from Battery's specific ones):
-
-  #+begin_src haskell
-    Run BatteryP ["BAT0"]
-                 ["-t", "<acstatus><watts> (<left>%)",
-                  "-L", "10", "-H", "80", "-p", "3",
-                  "--", "-O", "<fc=green>On</fc> - ", "-i", "",
-                  "-L", "-15", "-H", "-5",
-                  "-l", "red", "-m", "blue", "-h", "green"
-                  "-a", "notify-send -u critical 'Battery running out!!'",
-                  "-A", "3"]
-                 600
-  #+end_src
-
-  In the above example, the thresholds before the =--= separator affect
-  only the =<left>= and =<leftbar>= fields, while those after the
-  separator affect how =<watts>= is displayed. For this monitor, neither
-  the generic nor the specific options have any effect on =<timeleft>=.
-  We are also telling the monitor to execute the unix command
-  =notify-send= when the percentage left in the battery reaches 6%.
-
-  It is also possible to specify template variables in the =-O= and =-o=
-  switches, as in the following example:
-
-  #+begin_src haskell
-    Run BatteryP ["BAT0"]
-                 ["-t", "<acstatus>"
-                 , "-L", "10", "-H", "80"
-                 , "-l", "red", "-h", "green"
-                 , "--", "-O", "Charging", "-o", "Battery: <left>%"
-                 ] 10
-  #+end_src
-
-- The "idle" AC state is selected whenever the AC power entering the
-  battery is zero.
-
-** =BatteryN Dirs Args RefreshRate Alias=
-
-Works like =BatteryP=, but lets you specify an alias for the monitor
-other than "battery". Useful in case you one separate monitors for more
-than one battery.
-
-** =TopProc Args RefreshRate=
-
-- Aliases to =top=
-- Args: default monitor arguments. The low and high thresholds (=-L= and
-  =-H=) denote, for memory entries, the percent of the process memory
-  over the total amount of memory currently in use and, for cpu entries,
-  the activity percentage (i.e., the value of =cpuN=, which takes values
-  between 0 and 100).
-- Variables that can be used with the =-t/--template= argument: =no=,
-  =name1=, =cpu1=, =both1=, =mname1=, =mem1=, =mboth1=, =name2=, =cpu2=,
-  =both2=, =mname2=, =mem2=, =mboth2=, ...
-- Default template: =<both1>=
-- Displays the name and cpu/mem usage of running processes (=bothn= and
-  =mboth= display both, and is useful to specify an overall maximum
-  and/or minimum width, using the =-m/-M= arguments. =no= gives the
-  total number of processes.
-
-** =TopMem Args RefreshRate=
-
-- Aliases to =topmem=
-- Args: default monitor arguments. The low and high thresholds (=-L= and
-  =-H=) denote the percent of the process memory over the total amount
-  of memory currently in use.
-- Variables that can be used with the =-t/--template= argument:
-  =name1=, =mem1=, =both1=, =name2=, =mem2=, =both2=, ...
-- Default template: =<both1>=
-- Displays the name and RSS (resident memory size) of running processes
-  (=bothn= displays both, and is useful to specify an overall maximum
-  and/or minimum width, using the =-m/-M= arguments.
-
-** =Date Format Alias RefreshRate=
-
-- Format is a time format string, as accepted by the standard ISO C
-  =strftime= function (or Haskell's =formatCalendarTime=).  Basically,
-  if =date +"my-string"= works with your command then =Date= will handle
-  it correctly.
-
-- Timezone changes are picked up automatically every minute.
-
-- Sample usage:
-
-  #+begin_src haskell
-    Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10
-  #+end_src
-
-** =DateZone Format Locale Zone Alias RefreshRate=
-
-A variant of the =Date= monitor where one is able to explicitly set the
-time-zone, as well as the locale.
-
-- The format of =DateZone= is exactly the same as =Date=.
-
-- If =Locale= is =""= (the empty string) the default locale of the
-  system is used, otherwise use the given locale. If there are more
-  instances of =DateZone=, using the empty string as input for =Locale=
-  is not recommended.
+** Battery Monitors
+*** =Battery Args RefreshRate=
+
+ Same as
+
+ #+begin_src haskell
+   BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate
+ #+end_src
+
+*** =BatteryP Dirs Args RefreshRate=
+
+ - Aliases to =battery=
+
+ - Dirs: list of directories in =/sys/class/power_supply/= where to look
+   for the ACPI files of each battery. Example: =["BAT0","BAT1","BAT2"]=.
+   Only up to 3 existing directories will be searched.
+
+ - Args: default monitor arguments, plus the following specific ones
+   (these options, being specific to the monitor, are to be specified
+   after a =--= in the argument list):
+
+   - =-O=: string for AC "on" status (default: "On")
+   - =-i=: string for AC "idle" status (default: "On")
+   - =-o=: string for AC "off" status (default: "Off")
+   - =-L=: low power (=watts=) threshold (default: 10)
+   - =-H=: high power threshold (default: 12)
+   - =-l=: color to display power lower than the =-L= threshold
+   - =-m=: color to display power lower than the =-H= threshold
+   - =-h=: color to display power higher than the =-H= threshold
+   - =-p=: color to display positive power (battery charging)
+   - =-f=: file in =/sys/class/power_supply= with AC info (default:
+     "AC/online")
+   - =-A=: a number between 0 and 100, threshold below which the action
+     given by =-a=, if any, is performed (default: 5)
+   - =-a=: a string with a system command that is run when the percentage
+     left in the battery is less or equal than the threshold given by the
+     =-A= option. If not present, no action is undertaken.
+   - =-P=: to include a percentage symbol in =left=.
+   - =--on-icon-pattern=: dynamic string for current battery charge when
+     AC is "on" in =leftipat=.
+   - =--off-icon-pattern=: dynamic string for current battery charge when
+     AC is "off" in =leftipat=.
+   - =--idle-icon-pattern=: dynamic string for current battery charge
+     when AC is "idle" in =leftipat=.
+   - =--lows=: string for AC "off" status and power lower than the =-L=
+     threshold (default: "")
+   - =--mediums=: string for AC "off" status and power lower than the
+     =-H= threshold (default: "")
+   - =--highs=: string for AC "off" status and power higher than the =-H=
+     threshold (default: "")
+
+ - Variables that can be used with the =-t/--template= argument:
+   =left=, =leftbar=, =leftvbar=, =leftipat=, =timeleft=, =watts=,
+   =acstatus=
+
+ - Default template: =Batt: <watts>, <left>% / <timeleft>=
+
+ - Example (note that you need "--" to separate regular monitor options
+   from Battery's specific ones):
 
-- =Zone= is the name of the =TimeZone=. It is assumed that the time-zone
-  database is stored in =/usr/share/zoneinfo/=. If the empty string is
-  given as =Zone=, the default system time is used.
-
-- Sample usage:
-
-  #+begin_src haskell
-    Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10
-  #+end_src
-
-** =DiskU Disks Args RefreshRate=
+   #+begin_src haskell
+     Run BatteryP ["BAT0"]
+                  ["-t", "<acstatus><watts> (<left>%)",
+                   "-L", "10", "-H", "80", "-p", "3",
+                   "--", "-O", "<fc=green>On</fc> - ", "-i", "",
+                   "-L", "-15", "-H", "-5",
+                   "-l", "red", "-m", "blue", "-h", "green"
+                   "-a", "notify-send -u critical 'Battery running out!!'",
+                   "-A", "3"]
+                  600
+   #+end_src
 
-- Aliases to =disku=
+   In the above example, the thresholds before the =--= separator affect
+   only the =<left>= and =<leftbar>= fields, while those after the
+   separator affect how =<watts>= is displayed. For this monitor, neither
+   the generic nor the specific options have any effect on =<timeleft>=.
+   We are also telling the monitor to execute the unix command
+   =notify-send= when the percentage left in the battery reaches 6%.
 
-- 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>=, =<freeipat>=, =<usedbar>=,
-  =<usedvbar>= or =<usedipat>= for total, free, used, free percentage
-  and used percentage of the given file system capacity.
+   It is also possible to specify template variables in the =-O= and =-o=
+   switches, as in the following example:
 
-- Thresholds refer to usage percentage.
+   #+begin_src haskell
+     Run BatteryP ["BAT0"]
+                  ["-t", "<acstatus>"
+                  , "-L", "10", "-H", "80"
+                  , "-l", "red", "-h", "green"
+                  , "--", "-O", "Charging", "-o", "Battery: <left>%"
+                  ] 10
+   #+end_src
 
-- Args: default monitor arguments. =-t/--template= is ignored. Plus
+ - The "idle" AC state is selected whenever the AC power entering the
+   battery is zero.
 
-  - =--free-icon-pattern=: dynamic string for free disk space in
-    =freeipat=.
-  - =--used-icon-pattern=: dynamic string for used disk space in
-    =usedipat=.
+*** =BatteryN Dirs Args RefreshRate Alias=
 
-- Default template: none (you must specify a template for each file
-  system).
+ Works like =BatteryP=, but lets you specify an alias for the monitor
+ other than "battery". Useful in case you one separate monitors for more
+ than one battery.
+** Cpu and Memory Monitors
+*** =Cpu Args RefreshRate=
 
-- Example:
+ - Aliases to =cpu=
+ - Args: default monitor arguments, plus:
 
-  #+begin_src haskell
-    DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")]
-          ["-L", "20", "-H", "50", "-m", "1", "-p", "3"]
-          20
-  #+end_src
+   - =--load-icon-pattern=: dynamic string for cpu load in =ipat=
 
-** =DiskIO Disks Args RefreshRate=
+ - Thresholds refer to percentage of CPU load
+ - Variables that can be used with the =-t/--template= argument:
+   =total=, =bar=, =vbar=, =ipat=, =user=, =nice=, =system=, =idle=,
+   =iowait=
+ - Default template: =Cpu: <total>%=
 
-- Aliases to =diskio=
+*** =MultiCpu Args RefreshRate=
 
-- 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, as well as =<totalb>=,
-  =<readb>=, =<writeb>=, which report number of bytes during the last
-  refresh period rather than speed. There are also bar versions of each:
-  =<totalbar>=, =<totalvbar>=, =<totalipat>=, =<readbar>=, =<readvbar>=,
-  =<readipat>=, =<writebar>=, =<writevbar>=, and =<writeipat>=; and
-  their "bytes" counterparts: =<totalbbar>=, =<totalbvbar>=,
-  =<totalbipat>=, =<readbbar>=, =<readbvbar>=, =<readbipat>=,
-  =<writebbar>=, =<writebvbar>=, and =<writebipat>=.
+ - Aliases to =multicpu=
+ - Args: default monitor arguments, plus:
 
-- Thresholds refer to speed in b/s
+   - =--load-icon-pattern=: dynamic string for overall cpu load in
+     =ipat=.
+   - =--load-icon-patterns=: dynamic string for each cpu load in
+     =autoipat=, =ipat{i}=. This option can be specified several times.
+     nth option corresponds to nth cpu.
+   - =--fallback-icon-pattern=: dynamic string used by =autoipat= and
+     =ipat{i}= when no =--load-icon-patterns= has been provided for
+     =cpu{i}=
+   - =--contiguous-icons=: flag (no value needs to be provided) that
+     causes the load icons to be drawn without padding.
 
-- Args: default monitor arguments. =-t/--template= is ignored. Plus
+ - Thresholds refer to percentage of CPU load
+ - Variables that can be used with the =-t/--template= argument:
+   =autototal=, =autobar=, =autovbar=, =autoipat=, =autouser=,
+   =autonice=, =autosystem=, =autoidle=, =total=, =bar=, =vbar=, =ipat=,
+   =user=, =nice=, =system=, =idle=, =total0=, =bar0=, =vbar0=, =ipat0=,
+   =user0=, =nice0=, =system0=, =idle0=, ... The auto* variables
+   automatically detect the number of CPUs on the system and display one
+   entry for each.
+ - Default template: =Cpu: <total>%=
 
-  - =--total-icon-pattern=: dynamic string for total disk I/O in
-    =<totalipat>=.
-  - =--write-icon-pattern=: dynamic string for write disk I/O in
-    =<writeipat>=.
-  - =--read-icon-pattern=: dynamic string for read disk I/O in
-    =<readipat>=.
+*** =CpuFreq Args RefreshRate=
 
-- Default template: none (you must specify a template for each file
-  system).
+ - Aliases to =cpufreq=
 
-- Example:
+ - Args: default monitor arguments
 
-  #+begin_src haskell
-    DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10
-  #+end_src
+ - Thresholds refer to frequency in GHz
 
-** =ThermalZone Number Args RefreshRate=
+ - Variables that can be used with the =-t/--template= argument:
+   =cpu0=, =cpu1=, .., =cpuN=
 
-- Aliases to "thermaln": so =ThermalZone 0 []= can be used in template
-  as =%thermal0%=
+ - Default template: =Freq: <cpu0>GHz=
 
-- Thresholds refer to temperature in degrees
+ - This monitor requires acpi_cpufreq module to be loaded in kernel
 
-- Args: default monitor arguments
+ - Example:
 
-- Variables that can be used with the =-t/--template= argument: =temp=
+   #+begin_src haskell
+     Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",
+                  "-l", "lightblue", "-n","white", "-h", "red"] 50
+   #+end_src
 
-- Default template: =<temp>C=
+*** =CoreTemp Args RefreshRate=
 
-- This plugin works only on systems with devices having thermal zone.
-  Check directories in =/sys/class/thermal= for possible values of the
-  zone number (e.g., 0 corresponds to =thermal_zone0= in that
-  directory).
+ - Aliases to =coretemp=
 
-- Example:
+ - Args: default monitor arguments
 
-  #+begin_src haskell
-    Run ThermalZone 0 ["-t","<id>: <temp>C"] 30
-  #+end_src
+ - Thresholds refer to temperature in degrees
 
-** =Thermal Zone Args RefreshRate=
+ - Variables that can be used with the =-t/--template= argument:
+   =core0=, =core1=, .., =coreN=
 
-- *This plugin is deprecated. Use =ThermalZone= instead.*
+ - Default template: =Temp: <core0>C=
 
-- Aliases to the Zone: so =Thermal "THRM" []= can be used in template as
-  =%THRM%=
+ - This monitor requires coretemp module to be loaded in kernel
 
-- Args: default monitor arguments
+ - Example:
 
-- Thresholds refer to temperature in degrees
+   #+begin_src haskell
+     Run CoreTemp ["-t", "Temp:<core0>|<core1>C",
+                   "-L", "40", "-H", "60",
+                   "-l", "lightblue", "-n", "gray90", "-h", "red"] 50
+   #+end_src
 
-- Variables that can be used with the =-t/--template= argument: =temp=
+*** =MultiCoreTemp Args RefreshRate=
 
-- Default template: =Thm: <temp>C=
+ - Aliases to =multicoretemp=
 
-- This plugin works only on systems with devices having thermal zone.
-  Check directories in /proc/acpi/thermal_zone for possible values.
+ - Args: default monitor arguments, plus:
 
-- Example:
+   - =--max-icon-pattern=: dynamic string for overall cpu load in
+     =maxipat=.
+   - =--avg-icon-pattern=: dynamic string for overall cpu load in
+     =avgipat=.
+   - =--mintemp=: temperature in degree Celsius, that sets the lower
+     limit for percentage calculation.
+   - =--maxtemp=: temperature in degree Celsius, that sets the upper
+     limit for percentage calculation.
+   - =--hwmonitor-path=: this monitor tries to find coretemp devices by
+     looking for them in directories following the pattern
+     =/sys/bus/platform/devices/coretemp.*/hwmon/hwmon*=, but some
+     processors (notably Ryzen) might expose those files in a different
+     tree (e.g., Ryzen) puts them somewhere in "/sys/class/hwmon/hwmon*",
+     and the lookup is most costly. With this option, it is possible to
+     explicitly specify the full path to the directory where the
+     =tempN_label= and =tempN_input= files are located.
 
-  #+begin_src haskell
-    Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50
-  #+end_src
+ - Thresholds refer to temperature in degree Celsius
 
-** =CpuFreq Args RefreshRate=
+ - Variables that can be used with the =-t/--template= argument: =max=,
+   =maxpc=, =maxbar=, =maxvbar=, =maxipat=, =avg=, =avgpc=, =avgbar=,
+   =avgvbar=, =avgipat=, =core0=, =core1=, ..., =coreN=
 
-- Aliases to =cpufreq=
+   The /pc, /bar, /vbar and /ipat variables are showing percentages on
+   the scale defined by =--mintemp= and =--maxtemp=. The max* and avg*
+   variables to the highest and the average core temperature.
 
-- Args: default monitor arguments
+ - Default template: =Temp: <max>°C - <maxpc>%=
 
-- Thresholds refer to frequency in GHz
+ - This monitor requires coretemp module to be loaded in kernel
 
-- Variables that can be used with the =-t/--template= argument:
-  =cpu0=, =cpu1=, .., =cpuN=
+ - Example:
 
-- Default template: =Freq: <cpu0>GHz=
+   #+begin_src haskell
+     Run MultiCoreTemp ["-t", "Temp: <avg>°C | <avgpc>%",
+                        "-L", "60", "-H", "80",
+                        "-l", "green", "-n", "yellow", "-h", "red",
+                        "--", "--mintemp", "20", "--maxtemp", "100"] 50
+   #+end_src
+*** =Memory Args RefreshRate=
+
+ - Aliases to =memory=
+ - Args: default monitor arguments, plus:
+
+   - =--used-icon-pattern=: dynamic string for used memory ratio in
+     =usedipat=.
+   - =--free-icon-pattern=: dynamic string for free memory ratio in
+     =freeipat=.
+   - =--available-icon-pattern=: dynamic string for available memory
+     ratio in =availableipat=.
+
+ - Thresholds refer to percentage of used memory
+ - Variables that can be used with the =-t/--template= argument:
+   =total=, =free=, =buffer=, =cache=, =available=, =used=, =usedratio=,
+   =usedbar=, =usedvbar=, =usedipat=, =freeratio=, =freebar=, =freevbar=,
+   =freeipat=, =availableratio=, =availablebar=, =availablevbar=,
+   =availableipat=
+ - Default template: =Mem: <usedratio>% (<cache>M)=
+
+*** =Swap Args RefreshRate=
+
+ - Aliases to =swap=
+ - Args: default monitor arguments
+ - Thresholds refer to percentage of used swap
+ - Variables that can be used with the =-t/--template= argument:
+   =total=, =used=, =free=, =usedratio=
+ - Default template: =Swap: <usedratio>%=
+** Date Monitors
+*** =Date Format Alias RefreshRate=
+
+ - Format is a time format string, as accepted by the standard ISO C
+   =strftime= function (or Haskell's =formatCalendarTime=).  Basically,
+   if =date +"my-string"= works with your command then =Date= will handle
+   it correctly.
+
+ - Timezone changes are picked up automatically every minute.
+
+ - Sample usage:
 
-- This monitor requires acpi_cpufreq module to be loaded in kernel
+   #+begin_src haskell
+     Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10
+   #+end_src
 
-- Example:
+*** =DateZone Format Locale Zone Alias RefreshRate=
 
-  #+begin_src haskell
-    Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",
-                 "-l", "lightblue", "-n","white", "-h", "red"] 50
-  #+end_src
+ A variant of the =Date= monitor where one is able to explicitly set the
+ time-zone, as well as the locale.
 
-** =CoreTemp Args RefreshRate=
+ - The format of =DateZone= is exactly the same as =Date=.
 
-- Aliases to =coretemp=
+ - If =Locale= is =""= (the empty string) the default locale of the
+   system is used, otherwise use the given locale. If there are more
+   instances of =DateZone=, using the empty string as input for =Locale=
+   is not recommended.
 
-- Args: default monitor arguments
+ - =Zone= is the name of the =TimeZone=. It is assumed that the time-zone
+   database is stored in =/usr/share/zoneinfo/=. If the empty string is
+   given as =Zone=, the default system time is used.
 
-- Thresholds refer to temperature in degrees
+ - Sample usage:
 
-- Variables that can be used with the =-t/--template= argument:
-  =core0=, =core1=, .., =coreN=
+   #+begin_src haskell
+     Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10
+   #+end_src
+** Disk Monitors
+*** =DiskU Disks Args RefreshRate=
 
-- Default template: =Temp: <core0>C=
+ - Aliases to =disku=
 
-- This monitor requires coretemp module to be loaded in kernel
+ - 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>=, =<freeipat>=, =<usedbar>=,
+   =<usedvbar>= or =<usedipat>= for total, free, used, free percentage
+   and used percentage of the given file system capacity.
 
-- Example:
+ - Thresholds refer to usage percentage.
 
-  #+begin_src haskell
-    Run CoreTemp ["-t", "Temp:<core0>|<core1>C",
-                  "-L", "40", "-H", "60",
-                  "-l", "lightblue", "-n", "gray90", "-h", "red"] 50
-  #+end_src
+ - Args: default monitor arguments. =-t/--template= is ignored. Plus
 
-** =MultiCoreTemp Args RefreshRate=
+   - =--free-icon-pattern=: dynamic string for free disk space in
+     =freeipat=.
+   - =--used-icon-pattern=: dynamic string for used disk space in
+     =usedipat=.
 
-- Aliases to =multicoretemp=
+ - Default template: none (you must specify a template for each file
+   system).
 
-- Args: default monitor arguments, plus:
+ - Example:
 
-  - =--max-icon-pattern=: dynamic string for overall cpu load in
-    =maxipat=.
-  - =--avg-icon-pattern=: dynamic string for overall cpu load in
-    =avgipat=.
-  - =--mintemp=: temperature in degree Celsius, that sets the lower
-    limit for percentage calculation.
-  - =--maxtemp=: temperature in degree Celsius, that sets the upper
-    limit for percentage calculation.
-  - =--hwmonitor-path=: this monitor tries to find coretemp devices by
-    looking for them in directories following the pattern
-    =/sys/bus/platform/devices/coretemp.*/hwmon/hwmon*=, but some
-    processors (notably Ryzen) might expose those files in a different
-    tree (e.g., Ryzen) puts them somewhere in "/sys/class/hwmon/hwmon*",
-    and the lookup is most costly. With this option, it is possible to
-    explicitly specify the full path to the directory where the
-    =tempN_label= and =tempN_input= files are located.
+   #+begin_src haskell
+     DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")]
+           ["-L", "20", "-H", "50", "-m", "1", "-p", "3"]
+           20
+   #+end_src
 
-- Thresholds refer to temperature in degree Celsius
+*** =DiskIO Disks Args RefreshRate=
 
-- Variables that can be used with the =-t/--template= argument: =max=,
-  =maxpc=, =maxbar=, =maxvbar=, =maxipat=, =avg=, =avgpc=, =avgbar=,
-  =avgvbar=, =avgipat=, =core0=, =core1=, ..., =coreN=
+ - Aliases to =diskio=
 
-  The /pc, /bar, /vbar and /ipat variables are showing percentages on
-  the scale defined by =--mintemp= and =--maxtemp=. The max* and avg*
-  variables to the highest and the average core temperature.
+ - 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, as well as =<totalb>=,
+   =<readb>=, =<writeb>=, which report number of bytes during the last
+   refresh period rather than speed. There are also bar versions of each:
+   =<totalbar>=, =<totalvbar>=, =<totalipat>=, =<readbar>=, =<readvbar>=,
+   =<readipat>=, =<writebar>=, =<writevbar>=, and =<writeipat>=; and
+   their "bytes" counterparts: =<totalbbar>=, =<totalbvbar>=,
+   =<totalbipat>=, =<readbbar>=, =<readbvbar>=, =<readbipat>=,
+   =<writebbar>=, =<writebvbar>=, and =<writebipat>=.
 
-- Default template: =Temp: <max>°C - <maxpc>%=
+ - Thresholds refer to speed in b/s
 
-- This monitor requires coretemp module to be loaded in kernel
+ - Args: default monitor arguments. =-t/--template= is ignored. Plus
 
-- Example:
+   - =--total-icon-pattern=: dynamic string for total disk I/O in
+     =<totalipat>=.
+   - =--write-icon-pattern=: dynamic string for write disk I/O in
+     =<writeipat>=.
+   - =--read-icon-pattern=: dynamic string for read disk I/O in
+     =<readipat>=.
 
-  #+begin_src haskell
-    Run MultiCoreTemp ["-t", "Temp: <avg>°C | <avgpc>%",
-                       "-L", "60", "-H", "80",
-                       "-l", "green", "-n", "yellow", "-h", "red",
-                       "--", "--mintemp", "20", "--maxtemp", "100"] 50
-  #+end_src
+ - Default template: none (you must specify a template for each file
+   system).
 
-** =Volume Mixer Element Args RefreshRate=
+ - Example:
 
-- Aliases to the mixer name and element name separated by a colon. Thus,
-  =Volume "default" "Master" [] 10= can be used as =%default:Master%=.
-- Args: default monitor arguments. Also accepts:
+   #+begin_src haskell
+     DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10
+   #+end_src
 
-  - =-O= /string/ On string
+** Keyboard Monitors
+*** =Kbd Opts=
 
-    - The string used in place of =<status>= when the mixer element is
-      on. Defaults to "[on]".
-    - Long option: =--on=
+ - Registers to XKB/X11-Events and output the currently active keyboard
+   layout. Supports replacement of layout names.
 
-  - =-o= /string/ Off string
+ - Aliases to =kbd=
 
-    - The string used in place of =<status>= when the mixer element is
-      off. Defaults to "[off]".
-    - Long option: =--off=
+ - Opts is a list of tuples:
 
-  - =-C= /color/ On color
+   - first element of the tuple is the search string
+   - second element of the tuple is the corresponding replacement
 
-    - The color to be used for =<status>= when the mixer element is on.
-      Defaults to "green".
-    - Long option: =--onc=
+ - Example:
 
-  - =-c= /color/ Off color
+   #+begin_src haskell
+     Run Kbd [("us(dvorak)", "DV"), ("us", "US")]
+   #+end_src
 
-    - The color to be used for =<status>= when the mixer element is off.
-      Defaults to "red".
-    - Long option: =--offc=
+*** =Locks=
 
-  - =--highd= /number/ High threshold for dB. Defaults to -5.0.
-  - =--lowd= /number/ Low threshold for dB. Defaults to -30.0.
-  - =--volume-icon-pattern= /string/ dynamic string for current volume
-    in =volumeipat=.
-  - =-H= /number/ High threshold for volume (in %). Defaults to 60.0.
+ - Displays the status of Caps Lock, Num Lock and Scroll Lock.
 
-    - Long option: =--highv=
+ - Aliases to =locks=
 
-  - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0.
+ - Example:
 
-    - Long option: =--lowv=
+   #+begin_src haskell
+     Run Locks
+   #+end_src
+** Process Monitors
+*** =TopProc Args RefreshRate=
+
+ - Aliases to =top=
+ - Args: default monitor arguments. The low and high thresholds (=-L= and
+   =-H=) denote, for memory entries, the percent of the process memory
+   over the total amount of memory currently in use and, for cpu entries,
+   the activity percentage (i.e., the value of =cpuN=, which takes values
+   between 0 and 100).
+ - Variables that can be used with the =-t/--template= argument: =no=,
+   =name1=, =cpu1=, =both1=, =mname1=, =mem1=, =mboth1=, =name2=, =cpu2=,
+   =both2=, =mname2=, =mem2=, =mboth2=, ...
+ - Default template: =<both1>=
+ - Displays the name and cpu/mem usage of running processes (=bothn= and
+   =mboth= display both, and is useful to specify an overall maximum
+   and/or minimum width, using the =-m/-M= arguments. =no= gives the
+   total number of processes.
+
+*** =TopMem Args RefreshRate=
+
+ - Aliases to =topmem=
+ - Args: default monitor arguments. The low and high thresholds (=-L= and
+   =-H=) denote the percent of the process memory over the total amount
+   of memory currently in use.
+ - Variables that can be used with the =-t/--template= argument:
+   =name1=, =mem1=, =both1=, =name2=, =mem2=, =both2=, ...
+ - Default template: =<both1>=
+ - Displays the name and RSS (resident memory size) of running processes
+   (=bothn= displays both, and is useful to specify an overall maximum
+   and/or minimum width, using the =-m/-M= arguments.
+** Thermal Monitors
+*** =ThermalZone Number Args RefreshRate=
+
+ - Aliases to "thermaln": so =ThermalZone 0 []= can be used in template
+   as =%thermal0%=
+
+ - Thresholds refer to temperature in degrees
+
+ - Args: default monitor arguments
+
+ - Variables that can be used with the =-t/--template= argument: =temp=
+
+ - Default template: =<temp>C=
+
+ - This plugin works only on systems with devices having thermal zone.
+   Check directories in =/sys/class/thermal= for possible values of the
+   zone number (e.g., 0 corresponds to =thermal_zone0= in that
+   directory).
+
+ - Example:
 
-  - =-h=: /string/ High string
+   #+begin_src haskell
+     Run ThermalZone 0 ["-t","<id>: <temp>C"] 30
+   #+end_src
 
-    - The string added in front of =<status>= when the mixer element is
-      on and the volume percentage is higher than the =-H= threshold.
-      Defaults to "".
-    - Long option: =--highs=
+*** =Thermal Zone Args RefreshRate=
 
-  - =-m=: /string/ Medium string
+ - *This plugin is deprecated. Use =ThermalZone= instead.*
 
-    - The string added in front of =<status>= when the mixer element is
-      on and the volume percentage is lower than the =-H= threshold.
-      Defaults to "".
-    - Long option: =--mediums=
+ - Aliases to the Zone: so =Thermal "THRM" []= can be used in template as
+   =%THRM%=
 
-  - =-l=: /string/ Low string
+ - Args: default monitor arguments
 
-    - The string added in front of =<status>= when the mixer element is
-      on and the volume percentage is lower than the =-L= threshold.
-      Defaults to "".
-    - Long option: =--lows=
+ - Thresholds refer to temperature in degrees
 
-- Variables that can be used with the =-t/--template= argument:
-  =volume=, =volumebar=, =volumevbar=, =volumeipat=, =dB=, =status=,
-  =volumestatus=
-- 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>=
-- Requires the package [[http://hackage.haskell.org/package/alsa-core][alsa-core]] and [[http://hackage.haskell.org/package/alsa-mixer][alsa-mixer]] installed in your
-  system. In addition, to activate this plugin you must pass the
-  =with_alsa= flag during compilation.
+ - Variables that can be used with the =-t/--template= argument: =temp=
 
-** =Alsa Mixer Element Args=
+ - Default template: =Thm: <temp>C=
 
-Like [[=Volume Mixer Element Args RefreshRate=][Volume]] but with the following differences:
+ - This plugin works only on systems with devices having thermal zone.
+   Check directories in /proc/acpi/thermal_zone for possible values.
 
-- Uses event-based refreshing via =alsactl monitor= instead of polling,
-  so it will refresh instantly when there's a volume change, and won't
-  use CPU until a change happens.
-- Aliases to =alsa:= followed by the mixer name and element name
-  separated by a colon. Thus, =Alsa "default" "Master" []= can be used
-  as =%alsa:default:Master%=.
-- Additional options (after the =--=):
-  - =--alsactl=/path/to/alsactl=: If this option is not specified,
-    =alsactl= will be sought in your =PATH= first, and failing that, at
-    =/usr/sbin/alsactl= (this is its location on Debian systems.
-    =alsactl monitor= works as a non-root user despite living in
-    =/usr/sbin=.).
-  - =stdbuf= (from coreutils) must be (and most probably already is) in
-    your =PATH=.
+ - Example:
 
-** =MPD Args RefreshRate=
+   #+begin_src haskell
+     Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50
+   #+end_src
+** Volume Monitors
+*** =Volume Mixer Element Args RefreshRate=
 
-- This monitor will only be compiled if you ask for it using the
-  =with_mpd= flag. It needs [[http://hackage.haskell.org/package/libmpd/][libmpd]] 5.0 or later (available on Hackage).
+ - Aliases to the mixer name and element name separated by a colon. Thus,
+   =Volume "default" "Master" [] 10= can be used as =%default:Master%=.
+ - Args: default monitor arguments. Also accepts:
 
-- Aliases to =mpd=
+   - =-O= /string/ On string
 
-- Args: default monitor arguments. In addition you can provide =-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, unless given in the additional
-  arguments =-p= (=--port=) and =-h= (=--host=). Also available:
+     - The string used in place of =<status>= when the mixer element is
+       on. Defaults to "[on]".
+     - Long option: =--on=
 
-  - =lapsed-icon-pattern=: dynamic string for current track position in
-    =ipat=.
+   - =-o= /string/ Off string
 
-- Variables that can be used with the =-t/--template= argument: =bar=,
-  =vbar=, =ipat=, =state=, =statei=, =volume=, =length=, =lapsed=,
-  =remaining=, =plength= (playlist length), =ppos= (playlist position),
-  =flags= (ncmpcpp-style playback mode), =name=, =artist=, =composer=,
-  =performer=, =album=, =title=, =track=, =file=, =genre=, =date=
+     - The string used in place of =<status>= when the mixer element is
+       off. Defaults to "[off]".
+     - Long option: =--off=
 
-- Default template: =MPD: <state>=
+   - =-C= /color/ On color
 
-- Example (note that you need "--" to separate regular monitor options
-  from MPD's specific ones):
+     - The color to be used for =<status>= when the mixer element is on.
+       Defaults to "green".
+     - Long option: =--onc=
 
-  #+begin_src haskell
-    Run MPD ["-t",
-             "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]",
-             "--", "-P", ">>", "-Z", "|", "-S", "><"] 10
-  #+end_src
+   - =-c= /color/ Off color
 
-** =MPDX Args RefreshRate Alias=
+     - The color to be used for =<status>= when the mixer element is off.
+       Defaults to "red".
+     - Long option: =--offc=
 
-Like =MPD= but uses as alias its last argument instead of "mpd".
+   - =--highd= /number/ High threshold for dB. Defaults to -5.0.
+   - =--lowd= /number/ Low threshold for dB. Defaults to -30.0.
+   - =--volume-icon-pattern= /string/ dynamic string for current volume
+     in =volumeipat=.
+   - =-H= /number/ High threshold for volume (in %). Defaults to 60.0.
 
-** =Mpris1 PlayerName Args RefreshRate=
+     - Long option: =--highv=
 
-- Aliases to =mpris1=
+   - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0.
 
-- Requires [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages. To activate, pass the =with_mpris=
-  flag during compilation.
+     - Long option: =--lowv=
 
-- PlayerName: player supporting MPRIS v1 protocol. Some players need
-  this to be an all lowercase name (e.g. "spotify"), but some others
-  don't.
+   - =-h=: /string/ High string
 
-- Args: default monitor arguments.
+     - The string added in front of =<status>= when the mixer element is
+       on and the volume percentage is higher than the =-H= threshold.
+       Defaults to "".
+     - Long option: =--highs=
 
-- Variables that can be used with the =-t/--template= argument:
-  =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=
+   - =-m=: /string/ Medium string
 
-- Default template: =<artist> - <title>=
+     - The string added in front of =<status>= when the mixer element is
+       on and the volume percentage is lower than the =-H= threshold.
+       Defaults to "".
+     - Long option: =--mediums=
 
-- Example:
+   - =-l=: /string/ Low string
 
-  #+begin_src haskell
-    Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10
-  #+end_src
+     - The string added in front of =<status>= when the mixer element is
+       on and the volume percentage is lower than the =-L= threshold.
+       Defaults to "".
+     - Long option: =--lows=
 
-** =Mpris2 PlayerName Args RefreshRate=
+ - Variables that can be used with the =-t/--template= argument:
+   =volume=, =volumebar=, =volumevbar=, =volumeipat=, =dB=, =status=,
+   =volumestatus=
+ - 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>=
+ - Requires the package [[http://hackage.haskell.org/package/alsa-core][alsa-core]] and [[http://hackage.haskell.org/package/alsa-mixer][alsa-mixer]] installed in your
+   system. In addition, to activate this plugin you must pass the
+   =with_alsa= flag during compilation.
 
-- Aliases to =mpris2=
+*** =Alsa Mixer Element Args=
 
-- Requires [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages. To activate, pass the =with_mpris=
-  flag during compilation.
+ Like [[=Volume Mixer Element Args RefreshRate=][Volume]] but with the following differences:
 
-- PlayerName: player supporting MPRIS v2 protocol. Some players need
-  this to be an all lowercase name (e.g. "spotify"), but some others
-  don't.
+ - Uses event-based refreshing via =alsactl monitor= instead of polling,
+   so it will refresh instantly when there's a volume change, and won't
+   use CPU until a change happens.
+ - Aliases to =alsa:= followed by the mixer name and element name
+   separated by a colon. Thus, =Alsa "default" "Master" []= can be used
+   as =%alsa:default:Master%=.
+ - Additional options (after the =--=):
+   - =--alsactl=/path/to/alsactl=: If this option is not specified,
+     =alsactl= will be sought in your =PATH= first, and failing that, at
+     =/usr/sbin/alsactl= (this is its location on Debian systems.
+     =alsactl monitor= works as a non-root user despite living in
+     =/usr/sbin=.).
+   - =stdbuf= (from coreutils) must be (and most probably already is) in
+     your =PATH=.
+** Mail Monitors
+*** =Mail Args Alias=
 
-- Args: default monitor arguments.
+ - Args: list of maildirs in form =[("name1","path1"),...]=. Paths may
+   start with a '~' to expand to the user's home directory.
 
-- Variables that can be used with the =-t/--template= argument:
-  =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=,
-  =composer=, =genre=
+ - This plugin requires inotify support in your Linux kernel and the
+   [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during
+   compilation.
 
-- Default template: =<artist> - <title>=
+ - Example:
 
-- Example:
+   #+begin_src haskell
+     Run Mail [("inbox", "~/var/mail/inbox"),
+               ("lists", "~/var/mail/lists")]
+              "mail"
+   #+end_src
 
-  #+begin_src haskell
-    Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10
-  #+end_src
+*** =MailX Args Opts Alias=
 
-** =Mail Args Alias=
+ - Args: list of maildirs in form =[("name1","path1","color1"),...]=.
+   Paths may start with a '~' to expand to the user's home directory.
+   When mails are present, counts are displayed with the given name and
+   color.
 
-- Args: list of maildirs in form =[("name1","path1"),...]=. Paths may
-  start with a '~' to expand to the user's home directory.
+ - Opts is a possibly empty list of options, as flags. Possible values:
+   -d dir --dir dir a string giving the base directory where maildir
+   files with a relative path live. -p prefix --prefix prefix a string
+   giving a prefix for the list of displayed mail counts -s suffix
+   --suffix suffix a string giving a suffix for the list of displayed
+   mail counts
 
-- This plugin requires inotify support in your Linux kernel and the
-  [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during
-  compilation.
+ - This plugin requires inotify support in your Linux kernel and the
+   [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during
+   compilation.
 
-- Example:
+ - Example:
 
-  #+begin_src haskell
-    Run Mail [("inbox", "~/var/mail/inbox"),
-              ("lists", "~/var/mail/lists")]
-             "mail"
-  #+end_src
+   #+begin_src haskell
+     Run MailX [("I", "inbox", "green"),
+                ("L", "lists", "orange")]
+               ["-d", "~/var/mail", "-p", " ", "-s", " "]
+               "mail"
+   #+end_src
 
-** =MailX Args Opts Alias=
+*** =MBox Mboxes Opts Alias=
 
-- Args: list of maildirs in form =[("name1","path1","color1"),...]=.
-  Paths may start with a '~' to expand to the user's home directory.
-  When mails are present, counts are displayed with the given name and
-  color.
+ - Mboxes a list of mbox files of the form =[("name", "path", "color")]=,
+   where name is the displayed name, path the absolute or relative (to
+   BaseDir) path of the mbox file, and color the color to use to display
+   the mail count (use an empty string for the default).
 
-- Opts is a possibly empty list of options, as flags. Possible values:
-  -d dir --dir dir a string giving the base directory where maildir
-  files with a relative path live. -p prefix --prefix prefix a string
-  giving a prefix for the list of displayed mail counts -s suffix
-  --suffix suffix a string giving a suffix for the list of displayed
-  mail counts
+ - Opts is a possibly empty list of options, as flags. Possible values:
+   -a --all (no arg) Show all mailboxes, even if empty. -u (no arg) Show
+   only the mailboxes' names, sans counts. -d dir --dir dir a string
+   giving the base directory where mbox files with a relative path live.
+   -p prefix --prefix prefix a string giving a prefix for the list of
+   displayed mail counts -s suffix --suffix suffix a string giving a
+   suffix for the list of displayed mail counts
 
-- This plugin requires inotify support in your Linux kernel and the
-  [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during
-  compilation.
+ - Paths may start with a '~' to expand to the user's home directory.
 
-- Example:
+ - This plugin requires inotify support in your Linux kernel and the
+   [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during
+   compilation.
 
-  #+begin_src haskell
-    Run MailX [("I", "inbox", "green"),
-               ("L", "lists", "orange")]
-              ["-d", "~/var/mail", "-p", " ", "-s", " "]
-              "mail"
-  #+end_src
+ - Example. The following command look for mails in =/var/mail/inbox= and
+   =~/foo/mbox=, and will put a space in front of the printed string
+   (when it's not empty); it can be used in the template with the alias
+   =mbox=:
 
-** =MBox Mboxes Opts Alias=
+   #+begin_src haskell
+     Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]
+              ["-d", "/var/mail/", "-p", " "] "mbox"
+   #+end_src
 
-- Mboxes a list of mbox files of the form =[("name", "path", "color")]=,
-  where name is the displayed name, path the absolute or relative (to
-  BaseDir) path of the mbox file, and color the color to use to display
-  the mail count (use an empty string for the default).
+*** =NotmuchMail Alias Args Rate=
 
-- Opts is a possibly empty list of options, as flags. Possible values:
-  -a --all (no arg) Show all mailboxes, even if empty. -u (no arg) Show
-  only the mailboxes' names, sans counts. -d dir --dir dir a string
-  giving the base directory where mbox files with a relative path live.
-  -p prefix --prefix prefix a string giving a prefix for the list of
-  displayed mail counts -s suffix --suffix suffix a string giving a
-  suffix for the list of displayed mail counts
+ This plugin checks for new mail, provided that this mail is indexed by
+ =notmuch=. In the =notmuch= spirit, this plugin checks for new *threads*
+ and not new individual messages.
 
-- Paths may start with a '~' to expand to the user's home directory.
+ - Alias: What name the plugin should have in your template string.
 
-- This plugin requires inotify support in your Linux kernel and the
-  [[http://hackage.haskell.org/package/hinotify/][hinotify]] package. To activate, pass the =with_inotify= flag during
-  compilation.
+ - Args: A list of =MailItem= s of the form
 
-- Example. The following command look for mails in =/var/mail/inbox= and
-  =~/foo/mbox=, and will put a space in front of the printed string
-  (when it's not empty); it can be used in the template with the alias
-  =mbox=:
+   #+begin_src haskell
+     [ MailItem "name" "address" "query"
+     ...
+     ]
+   #+end_src
 
-  #+begin_src haskell
-    Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]
-             ["-d", "/var/mail/", "-p", " "] "mbox"
-  #+end_src
+   or, using explicit record syntax:
 
-** =NotmuchMail Alias Args Rate=
+   #+begin_src haskell
+     [ MailItem
+         { name    = "name"
+         , address = "address"
+         , query   = "query"
+         }
+       ...
+     ]
+   #+end_src
 
-This plugin checks for new mail, provided that this mail is indexed by
-=notmuch=. In the =notmuch= spirit, this plugin checks for new *threads*
-and not new individual messages.
+   where
 
-- Alias: What name the plugin should have in your template string.
+   - =name= is what gets printed in the status bar before the number of
+     new threads.
+   - =address= is the e-mail address of the recipient, i.e. we only query
+     mail that was send to this particular address (in more concrete
+     terms, we pass the address to the =to:= constructor when performing
+     the search). If =address= is empty, we search through all unread
+     mail, regardless of whom it was sent to.
+   - =query= is funneled to =notmuch search= verbatim. For the general
+     query syntax, consult =notmuch search --help=, as well as
+     =notmuch-search-terms(7)=. Note that the =unread= tag is *always*
+     added in front of the query and composed with it via an *and*.
 
-- Args: A list of =MailItem= s of the form
+ - Rate: Rate with which to update the plugin (in deciseconds).
 
-  #+begin_src haskell
-    [ MailItem "name" "address" "query"
-    ...
-    ]
-  #+end_src
+ - Example:
 
-  or, using explicit record syntax:
+   - A single =MailItem= that displays all unread threads from the given
+     address:
 
-  #+begin_src haskell
-    [ MailItem
-        { name    = "name"
-        , address = "address"
-        , query   = "query"
-        }
-      ...
-    ]
-  #+end_src
+     #+begin_src haskell
+       MailItem "mbs:" "soliditsallgood@mailbox.org" ""
+     #+end_src
 
-  where
+   - A single =MailItem= that displays all unread threads with
+     "[My-Subject]" somewhere in the title:
 
-  - =name= is what gets printed in the status bar before the number of
-    new threads.
-  - =address= is the e-mail address of the recipient, i.e. we only query
-    mail that was send to this particular address (in more concrete
-    terms, we pass the address to the =to:= constructor when performing
-    the search). If =address= is empty, we search through all unread
-    mail, regardless of whom it was sent to.
-  - =query= is funneled to =notmuch search= verbatim. For the general
-    query syntax, consult =notmuch search --help=, as well as
-    =notmuch-search-terms(7)=. Note that the =unread= tag is *always*
-    added in front of the query and composed with it via an *and*.
+     #+begin_src haskell
+       MailItem "S:" "" "subject:[My-Subject]"
+     #+end_src
 
-- Rate: Rate with which to update the plugin (in deciseconds).
+   - A full example of a =NotmuchMail= configuration:
 
-- Example:
+     #+begin_src haskell
+       Run NotmuchMail "mail"  -- name for the template string
+         [ -- All unread mail to the below address, but nothing that's tagged
+           -- with @lists@ or @haskell@.
+           MailItem "mbs:"
+                    "soliditsallgood@mailbox.org"
+                    "not tag:lists and not tag:haskell"
 
-  - A single =MailItem= that displays all unread threads from the given
-    address:
+           -- All unread mail that has @[Haskell-Cafe]@ in the subject line.
+         , MailItem "C:" "" "subject:[Haskell-Cafe]"
 
-    #+begin_src haskell
-      MailItem "mbs:" "soliditsallgood@mailbox.org" ""
-    #+end_src
+           -- All unread mail that's tagged as @lists@, but not @haskell@.
+         , MailItem "H:" "" "tag:lists and not tag:haskell"
+         ]
+         600                   -- update every 60 seconds
+     #+end_src
 
-  - A single =MailItem= that displays all unread threads with
-    "[My-Subject]" somewhere in the title:
+** Music Monitors
+*** =MPD Args RefreshRate=
 
-    #+begin_src haskell
-      MailItem "S:" "" "subject:[My-Subject]"
-    #+end_src
+ - This monitor will only be compiled if you ask for it using the
+   =with_mpd= flag. It needs [[http://hackage.haskell.org/package/libmpd/][libmpd]] 5.0 or later (available on Hackage).
 
-  - A full example of a =NotmuchMail= configuration:
+ - Aliases to =mpd=
 
-    #+begin_src haskell
-      Run NotmuchMail "mail"  -- name for the template string
-        [ -- All unread mail to the below address, but nothing that's tagged
-          -- with @lists@ or @haskell@.
-          MailItem "mbs:"
-                   "soliditsallgood@mailbox.org"
-                   "not tag:lists and not tag:haskell"
+ - Args: default monitor arguments. In addition you can provide =-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, unless given in the additional
+   arguments =-p= (=--port=) and =-h= (=--host=). Also available:
 
-          -- All unread mail that has @[Haskell-Cafe]@ in the subject line.
-        , MailItem "C:" "" "subject:[Haskell-Cafe]"
+   - =lapsed-icon-pattern=: dynamic string for current track position in
+     =ipat=.
 
-          -- All unread mail that's tagged as @lists@, but not @haskell@.
-        , MailItem "H:" "" "tag:lists and not tag:haskell"
-        ]
-        600                   -- update every 60 seconds
-    #+end_src
+ - Variables that can be used with the =-t/--template= argument: =bar=,
+   =vbar=, =ipat=, =state=, =statei=, =volume=, =length=, =lapsed=,
+   =remaining=, =plength= (playlist length), =ppos= (playlist position),
+   =flags= (ncmpcpp-style playback mode), =name=, =artist=, =composer=,
+   =performer=, =album=, =title=, =track=, =file=, =genre=, =date=
 
-** =XPropertyLog PropName=
+ - Default template: =MPD: <state>=
 
-- Aliases to =PropName=
-- Reads the X property named by =PropName= (a string) and displays its
-  value. The [[https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs][examples/xmonadpropwrite.hs script]] in xmobar's distribution
-  can be used to set the given property from the output of any other
-  program or script.
+ - Example (note that you need "--" to separate regular monitor options
+   from MPD's specific ones):
 
-** =UnsafeXPropertyLog PropName=
+   #+begin_src haskell
+     Run MPD ["-t",
+              "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]",
+              "--", "-P", ">>", "-Z", "|", "-S", "><"] 10
+   #+end_src
 
-- Aliases to =PropName=
-- Same as =XPropertyLog=, but the input is not filtered to avoid
-  injection of actions (cf. =UnsafeXMonadLog=). The program writing the
-  value of the read property is responsible of performing any needed
-  cleanups.
+*** =MPDX Args RefreshRate Alias=
 
-** =NamedXPropertyLog PropName Alias=
+ Like =MPD= but uses as alias its last argument instead of "mpd".
 
-- Aliases to =Alias=
-- Same as =XPropertyLog=, but a custom alias can be specified.
+*** =Mpris1 PlayerName Args RefreshRate=
 
-** =UnsafeNamedXPropertyLog PropName Alias=
+ - Aliases to =mpris1=
 
-- Aliases to =Alias=
-- Same as =UnsafeXPropertyLog=, but a custom alias can be specified.
+ - Requires [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages. To activate, pass the =with_mpris=
+   flag during compilation.
 
-** =Brightness Args RefreshRate=
+ - PlayerName: player supporting MPRIS v1 protocol. Some players need
+   this to be an all lowercase name (e.g. "spotify"), but some others
+   don't.
 
-- Aliases to =bright=
+ - Args: default monitor arguments.
 
-- Args: default monitor arguments, plus the following specif ones:
+ - Variables that can be used with the =-t/--template= argument:
+   =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=
 
-  - =-D=: directory in =/sys/class/backlight/= with files in it
-    (default: "acpi_video0")
-  - =-C=: file with the current brightness (default: actual_brightness)
-  - =-M=: file with the maximum brightness (default: max_brightness)
-  - =--brightness-icon-pattern=: dynamic string for current brightness
-    in =ipat=.
+ - Default template: =<artist> - <title>=
 
-- Variables that can be used with the =-t/--template= argument:
-  =vbar=, =percent=, =bar=, =ipat=
+ - Example:
 
-- Default template: =<percent>=
+   #+begin_src haskell
+     Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10
+   #+end_src
 
-- Example:
+*** =Mpris2 PlayerName Args RefreshRate=
 
-  #+begin_src haskell
-    Run Brightness ["-t", "<bar>"] 60
-  #+end_src
+ - Aliases to =mpris2=
 
-** =Kbd Opts=
+ - Requires [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages. To activate, pass the =with_mpris=
+   flag during compilation.
 
-- Registers to XKB/X11-Events and output the currently active keyboard
-  layout. Supports replacement of layout names.
+ - PlayerName: player supporting MPRIS v2 protocol. Some players need
+   this to be an all lowercase name (e.g. "spotify"), but some others
+   don't.
 
-- Aliases to =kbd=
+ - Args: default monitor arguments.
 
-- Opts is a list of tuples:
+ - Variables that can be used with the =-t/--template= argument:
+   =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=,
+   =composer=, =genre=
 
-  - first element of the tuple is the search string
-  - second element of the tuple is the corresponding replacement
+ - Default template: =<artist> - <title>=
 
-- Example:
+ - Example:
 
-  #+begin_src haskell
-    Run Kbd [("us(dvorak)", "DV"), ("us", "US")]
-  #+end_src
+   #+begin_src haskell
+     Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10
+   #+end_src
+** Network Monitors
+*** =Network Interface Args RefreshRate=
+
+ - Aliases to the interface name: so =Network "eth0" []= can be used as
+   =%eth0%=
+ - Thresholds refer to velocities expressed in Kb/s
+ - Args: default monitor arguments, plus:
+
+   - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=.
+   - =--tx-icon-pattern=: dynamic string for transmission rate in
+     =txipat=.
+   - =--up=: string used for the =up= variable value when the interface
+     is up.
+
+ - Variables that can be used with the =-t=/=--template= argument: =dev=,
+   =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=, =txipat=,
+   =up=. 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"
+ - Thresholds are expressed in Kb/s
+ - Args: default monitor arguments, plus:
+
+ - =--rx-icon-pattern=: dynamic string for reception rate in =rxipat=.
+ - =--tx-icon-pattern=: dynamic string for transmission rate in =txipat=
+ - =--devices=: comma-separated list of devices to show.
+
+ - Variables that can be used with the =-t=/=--template= argument:
+   =dev=, =rx=, =tx=, =rxbar=, =rxvbar=, =rxipat=, =txbar=, =txvbar=,
+   =txipat=.
+
+ 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=
+ - Example of usage of =--devices= option:
+
+     =["--", "--devices", "wlp2s0,enp0s20f41"]=
+
+*** =Wireless Interface Args RefreshRate=
+
+ - If set to "", first suitable wireless interface is used.
+ - Aliases to the interface name with the suffix "wi": thus,
+   =Wireless   "wlan0" []= can be used as =%wlan0wi%=, and
+   =Wireless "" []= as =%wi%=.
+ - Args: default monitor arguments, plus:
+
+   - =--quality-icon-pattern=: dynamic string for connection quality in
+     =qualityipat=.
+
+ - Variables that can be used with the =-t=/=--template= argument:
+   =ssid=, =signal=, =quality=, =qualitybar=, =qualityvbar=,
+   =qualityipat=
+ - Thresholds refer to link quality on a =[0, 100]= scale. Note that
+   =quality= is calculated from =signal= (in dBm) by a possibly lossy
+   conversion. It is also not taking into account many factors such as
+   noise level, air busy time, transcievers' capabilities and the others
+   which can have drastic impact on the link performance.
+ - Default template: =<ssid> <quality>=
+ - To activate this plugin you must pass the =with_nl80211= or the
+   =with_iwlib= flag during compilation.
+** Weather Monitors
+*** =Weather StationID Args RefreshRate=
+
+ - Aliases to the Station ID: so =Weather "LIPB" []= can be used in
+   template as =%LIPB%=
+ - Thresholds refer to temperature in the selected units
+ - Args: default monitor arguments, plus:
+
+   - =--weathers= /string/ : display a default string when the =weather=
+     variable is not reported.
+
+     - short option: =-w=
+     - Default: ""
+
+   - =--useManager= /bool/ : Whether to use one single manager per
+     monitor for managing network connections or create a new one every
+     time a connection is made.
+
+     - Short option: =-m=
+     - Default: True
+
+ - Variables that can be used with the =-t/--template= argument:
+   =station=, =stationState=, =year=, =month=, =day=, =hour=,
+   =windCardinal=, =windAzimuth=, =windMph=, =windKnots=, =windMs=,
+   =windKmh= =visibility=, =skyCondition=, =weather=, =tempC=, =tempF=,
+   =dewPointC=, =dewPointF=, =rh=, =pressure=
+ - Default template: =<station>: <tempC>C, rh <rh>% (<hour>)=
+ - Retrieves weather information from http://tgftp.nws.noaa.gov. Here is
+   an [[https://tgftp.nws.noaa.gov/data/observations/metar/decoded/CYLD.TXT][example]], also showcasing the kind of information that may be
+   extracted.
+
+*** =WeatherX StationID SkyConditions Args RefreshRate=
+
+ - Works in the same way as =Weather=, but takes an additional argument,
+   a list of pairs from sky conditions to their replacement (typically a
+   unicode string or an icon specification).
+ - Use the variable =skyConditionS= to display the replacement of the
+   corresponding sky condition. All other =Weather= template variables
+   are available as well.
+
+ For example:
+
+ #+begin_src haskell
+   WeatherX "LEBL"
+            [ ("clear", "🌣")
+            , ("sunny", "🌣")
+            , ("mostly clear", "🌤")
+            , ("mostly sunny", "🌤")
+            , ("partly sunny", "⛅")
+            , ("fair", "🌑")
+            , ("cloudy","☁")
+            , ("overcast","☁")
+            , ("partly cloudy", "⛅")
+            , ("mostly cloudy", "🌧")
+            , ("considerable cloudiness", "⛈")]
+            ["-t", "<fn=2><skyConditionS></fn> <tempC>° <rh>%  <windKmh> (<hour>)"
+            , "-L","10", "-H", "25", "--normal", "black"
+            , "--high", "lightgoldenrod4", "--low", "darkseagreen4"]
+            18000
+ #+end_src
+
+ As mentioned, the replacement string can also be an icon specification,
+ such as =("clear", "<icon=weather-clear.xbm/>")=.
+** Other Monitors
+*** =Brightness Args RefreshRate=
+
+ - Aliases to =bright=
+
+ - Args: default monitor arguments, plus the following specif ones:
+
+   - =-D=: directory in =/sys/class/backlight/= with files in it
+     (default: "acpi_video0")
+   - =-C=: file with the current brightness (default: actual_brightness)
+   - =-M=: file with the maximum brightness (default: max_brightness)
+   - =--brightness-icon-pattern=: dynamic string for current brightness
+     in =ipat=.
+
+ - Variables that can be used with the =-t/--template= argument:
+   =vbar=, =percent=, =bar=, =ipat=
+
+ - Default template: =<percent>=
+
+ - Example:
 
-** =Locks=
+   #+begin_src haskell
+     Run Brightness ["-t", "<bar>"] 60
+   #+end_src
 
-- Displays the status of Caps Lock, Num Lock and Scroll Lock.
+*** =CatInt n filename=
 
-- Aliases to =locks=
+ - Reads and displays an integer from the file whose path is =filename=
+   (especially useful with files in =/sys=).
 
-- Example:
+ - Aliases as =catn= (e.g. =Cat 0= as =cat0=, etc.) so you can have
+   several.
 
-  #+begin_src haskell
-    Run Locks
-  #+end_src
+ - Example:
 
-** =CatInt n filename=
+   #+begin_src haskell
+     Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50
+   #+end_src
 
-- Reads and displays an integer from the file whose path is =filename=
-  (especially useful with files in =/sys=).
+*** =CommandReader "/path/to/program" Alias=
 
-- Aliases as =catn= (e.g. =Cat 0= as =cat0=, etc.) so you can have
-  several.
+ - Runs the given program, and displays its standard output.
 
-- Example:
+*** =Uptime Args RefreshRate=
 
-  #+begin_src haskell
-    Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50
-  #+end_src
+ - Aliases to =uptime=
+ - Args: default monitor arguments. The low and high thresholds refer to
+   the number of days.
+ - Variables that can be used with the =-t/--template= argument: =days=,
+   =hours=, =minutes=, =seconds=. The total uptime is the sum of all
+   those fields. You can set the =-S= argument to =True= to add units to
+   the display of those numeric fields.
+ - Default template: =Up: <days>d <hours>h <minutes>m=
 
-** =UVMeter=
+*** =UVMeter=
 
-- Aliases to "uv" + station id. For example: =%uv Brisbane%= or
-  =%uv   Alice Springs%=
+ - Aliases to "uv" + station id. For example: =%uv Brisbane%= or
+   =%uv   Alice Springs%=
 
-- Args: default monitor arguments, plus:
+ - Args: default monitor arguments, plus:
 
-  - =--useManager= /bool/ : Whether to use one single manager per
-    monitor for managing network connections or create a new one every
-    time a connection is made.
+   - =--useManager= /bool/ : Whether to use one single manager per
+     monitor for managing network connections or create a new one every
+     time a connection is made.
 
-    - Short option: =-m=
-    - Default: True
+     - Short option: =-m=
+     - Default: True
 
-- /Reminder:/ Keep the refresh rate high, to avoid making unnecessary
-  requests every time the plug-in is run.
+ - /Reminder:/ Keep the refresh rate high, to avoid making unnecessary
+   requests every time the plug-in is run.
 
-- Station IDs can be found here:
-  http://www.arpansa.gov.au/uvindex/realtime/xml/uvvalues.xml
+ - Station IDs can be found here:
+   http://www.arpansa.gov.au/uvindex/realtime/xml/uvvalues.xml
 
-- Example:
+ - Example:
 
-  #+begin_src haskell
-    Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
-  #+end_src
+   #+begin_src haskell
+     Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
+   #+end_src
 
 * Interfacing with Window Managers