Move plugins to doc/plugins.org

This also moves Date and DateZone to the monitors section (as they are
monitors themselves).  A little bit of documentation was also
added/updated.

2 files changed, 1621 insertions, 1612 deletions

diff --git a/doc/plugins.org b/doc/plugins.org
new file mode 100644
index 0000000..f4d0754
--- /dev/null
+++ b/doc/plugins.org
@@ -0,0 +1,1621 @@
+#+OPTIONS: toc:t
+
+* System Monitor Plugins
+
+This is the description of the system monitor plugins available in
+xmobar. Some of them are only installed when an optional build option is
+set: we mention that fact, when needed, in their description.
+
+Each monitor has an =alias= to be used in the output template. 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.
+
+** 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
+(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,
+
+#+begin_src haskell
+  Run Brightness
+    [ "-t", "<ipat>"
+    , "--"
+    , "--brightness-icon-pattern", "<icon=bright_%%.xpm/>"
+    ] 30
+#+end_src
+
+Will display =bright_0.xpm= to =bright_8.xpm= depending on current
+brightness value.
+
+** Default Monitor Arguments
+
+Monitors accept a common set of arguments, described in the first
+subsection below. In addition, some monitors accept additional options
+that are specific to them. When specifying the list of arguments in your
+configuration, the common options come first, followed by =--=, followed
+by any monitor-specific options.
+
+These are the options available for all monitors below:
+
+- =-t= /string/ Output template
+
+  - Template for the monitor output. Field names must be enclosed
+    between pointy brackets (=<foo>=) and will be substituted by the
+    computed values. You can also specify the foreground (and
+    optionally, background) color for a region by bracketing it between
+    =<fc=fgcolor>= (or =<fc=fgcolor,bgcolor>=) and =</fc>=. The rest of
+    the template is output verbatim.
+  - Long option: =--template=
+  - Default value: per monitor (see above).
+
+- =-H= /number/ The high threshold.
+
+  - Numerical values higher than /number/ will be displayed with the
+    color specified by =-h= (see below).
+  - Long option: =--High=
+  - Default value: 66
+
+- =-L= /number/ The low threshold.
+
+  - Numerical values higher than /number/ and lower than the high
+    threshold will be displayed with the color specified by =-n= (see
+    below). Values lower than /number/ will use the =-l= color.
+  - Long option: =--Low=
+  - Default value: 33
+
+- =-h= /color/ High threshold color.
+
+  - Color for displaying values above the high threshold. /color/ can be
+    either a name (e.g. "blue") or an hexadecimal RGB (e.g. "#FF0000").
+  - Long option: =--high=
+  - Default: none (use the default foreground).
+
+- =-n= /color/ Color for 'normal' values
+
+  - Color used for values greater than the low threshold but lower than
+    the high one.
+  - Long option: =--normal=
+  - Default: none (use the default foreground).
+
+- =-l= /color/ The low threshold color
+
+  - Color for displaying values below the low threshold.
+  - Long option: =--low=
+  - Default: none (use the default foreground).
+
+- =-S= /boolean/ Display optional suffixes
+
+  - When set to a true designator ("True", "Yes" or "On"), optional
+    value suffixes such as the '%' symbol or optional units will be
+    displayed.
+  - Long option: =--suffix=
+  - Default: False.
+
+- =-p= /number/ Percentages padding
+
+  - Width, in number of digits, for quantities representing percentages.
+    For instance =-p 3= means that all percentages in the monitor will
+    be represented using 3 digits.
+  - Long option: =--ppad=
+  - Default value: 0 (don't pad)
+
+- =-d= /number/ Decimal digits
+
+  - Number of digits after the decimal period to use in float values.
+  - Long option: =--ddigits=
+  - Default value: 0 (display only integer part)
+
+- =-m= /number/ Minimum field width
+
+  - Minimum width, in number of characters, of the fields in the monitor
+    template. Values whose printed representation is shorter than this
+    value will be padded using the padding characters given by the =-c=
+    option with the alignment specified by =-a= (see below).
+  - Long option: =--minwidth=
+  - Default: 0
+
+- =-M= /number/ Maximum field width
+
+  - Maximum width, in number of characters, of the fields in the monitor
+    template. Values whose printed representation is longer than this
+    value will be truncated.
+  - Long option: =--maxwidth=
+  - Default: 0 (no maximum width)
+
+- =-e= /string/ Maximum width ellipsis
+
+  - Ellipsis to be added to the field when it has reached its max width.
+  - Long option: =--maxwidthellipsis=
+  - Default: "" (no ellipsis)
+
+- =-w= /number/ Fixed field width
+
+  - All fields will be set to this width, padding or truncating as
+    needed.
+  - Long option: =--width=
+  - Default: 0 (variable width)
+
+- =-T= /number/ Maximum total width
+
+  - Maximum total width of the text.
+  - Long option: =--maxtwidth=
+  - Default: 0 (no limit)
+
+- =-E= /string/ Maximum total width ellipsis
+
+  - Ellipsis to be added to the total text when it has reached its max
+    width.
+  - Long option: =--maxtwidthellipsis=
+  - Default: "" (no ellipsis)
+
+- =-c= /string/
+
+  - Characters used for padding. The characters of /string/ are used
+    cyclically. E.g., with =-P +- -w 6=, a field with value "foo" will
+    be represented as "+-+foo".
+  - Long option: =--padchars=
+  - Default value: " "
+
+- =-a= r|l Field alignment
+
+  - Whether to use right (r) or left (l) alignment of field values when
+    padding.
+  - Long option: =--align=
+  - Default value: r (padding to the left)
+
+- =-b= /string/ Bar background
+
+  - Characters used, cyclically, to draw the background of bars. For
+    instance, if you set this option to "·.", an empty bar will look
+    like this: =·.·.·.·.·.=
+  - Long option: =--bback=
+  - Default value: ":"
+
+- =-f= /string/ Bar foreground
+
+  - Characters used, cyclically, to draw the foreground of bars.
+  - Long option: =--bfore=
+  - Default value: "#"
+
+- =-W= /number/ Bar width
+
+  - Total number of characters used to draw bars.
+  - Long option: =--bwidth=
+  - Default value: 10
+  - Special value: 0. When this parameter is 0, the percentage to
+    display is interpreted as a position in the bar foreground string
+    (given by =-f=), and the character at that position is displayed.
+
+- =-x= /string/ N/A string
+
+  - String to be used when the monitor is not available
+  - Long option: =--nastring=
+  - Default value: "N/A"
+
+Commands' arguments must be set as a list. E.g.:
+
+#+begin_src haskell
+  Run Weather "EGPF" ["-t", "<station>: <tempC>C"] 36000
+#+end_src
+
+In this case xmobar will run the weather monitor, getting information
+for the weather station ID EGPF (Glasgow Airport, as a homage to GHC)
+every hour (36000 tenth of seconds), with a template that will output
+something like:
+
+#+begin_src shell
+  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.
+
+- =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=
+
+- 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>=, =<freeipat>=, =<usedbar>=,
+  =<usedvbar>= or =<usedipat>= for total, free, used, free percentage
+  and used percentage of the given file system capacity.
+
+- Thresholds refer to usage percentage.
+
+- Args: default monitor arguments. =-t/--template= is ignored. Plus
+
+  - =--free-icon-pattern=: dynamic string for free disk space in
+    =freeipat=.
+  - =--used-icon-pattern=: dynamic string for used disk space in
+    =usedipat=.
+
+- Default template: none (you must specify a template for each file
+  system).
+
+- Example:
+
+  #+begin_src haskell
+    DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")]
+          ["-L", "20", "-H", "50", "-m", "1", "-p", "3"]
+          20
+  #+end_src
+
+** =DiskIO Disks Args RefreshRate=
+
+- Aliases to =diskio=
+
+- 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>=.
+
+- Thresholds refer to speed in b/s
+
+- Args: default monitor arguments. =-t/--template= is ignored. Plus
+
+  - =--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>=.
+
+- Default template: none (you must specify a template for each file
+  system).
+
+- Example:
+
+  #+begin_src haskell
+    DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10
+  #+end_src
+
+** =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:
+
+  #+begin_src haskell
+    Run ThermalZone 0 ["-t","<id>: <temp>C"] 30
+  #+end_src
+
+** =Thermal Zone Args RefreshRate=
+
+- *This plugin is deprecated. Use =ThermalZone= instead.*
+
+- Aliases to the Zone: so =Thermal "THRM" []= can be used in template as
+  =%THRM%=
+
+- Args: default monitor arguments
+
+- Thresholds refer to temperature in degrees
+
+- Variables that can be used with the =-t/--template= argument: =temp=
+
+- Default template: =Thm: <temp>C=
+
+- This plugin works only on systems with devices having thermal zone.
+  Check directories in /proc/acpi/thermal_zone for possible values.
+
+- Example:
+
+  #+begin_src haskell
+    Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50
+  #+end_src
+
+** =CpuFreq Args RefreshRate=
+
+- Aliases to =cpufreq=
+
+- Args: default monitor arguments
+
+- Thresholds refer to frequency in GHz
+
+- Variables that can be used with the =-t/--template= argument:
+  =cpu0=, =cpu1=, .., =cpuN=
+
+- Default template: =Freq: <cpu0>GHz=
+
+- This monitor requires acpi_cpufreq module to be loaded in kernel
+
+- Example:
+
+  #+begin_src haskell
+    Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",
+                 "-l", "lightblue", "-n","white", "-h", "red"] 50
+  #+end_src
+
+** =CoreTemp Args RefreshRate=
+
+- Aliases to =coretemp=
+
+- Args: default monitor arguments
+
+- Thresholds refer to temperature in degrees
+
+- Variables that can be used with the =-t/--template= argument:
+  =core0=, =core1=, .., =coreN=
+
+- Default template: =Temp: <core0>C=
+
+- This monitor requires coretemp module to be loaded in kernel
+
+- Example:
+
+  #+begin_src haskell
+    Run CoreTemp ["-t", "Temp:<core0>|<core1>C",
+                  "-L", "40", "-H", "60",
+                  "-l", "lightblue", "-n", "gray90", "-h", "red"] 50
+  #+end_src
+
+** =MultiCoreTemp Args RefreshRate=
+
+- Aliases to =multicoretemp=
+
+- Args: default monitor arguments, plus:
+
+  - =--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.
+
+- Thresholds refer to temperature in degree Celsius
+
+- Variables that can be used with the =-t/--template= argument: =max=,
+  =maxpc=, =maxbar=, =maxvbar=, =maxipat=, =avg=, =avgpc=, =avgbar=,
+  =avgvbar=, =avgipat=, =core0=, =core1=, ..., =coreN=
+
+  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.
+
+- Default template: =Temp: <max>°C - <maxpc>%=
+
+- This monitor requires coretemp module to be loaded in kernel
+
+- Example:
+
+  #+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
+
+** =Volume Mixer Element Args RefreshRate=
+
+- 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:
+
+  - =-O= /string/ On string
+
+    - The string used in place of =<status>= when the mixer element is
+      on. Defaults to "[on]".
+    - Long option: =--on=
+
+  - =-o= /string/ Off string
+
+    - The string used in place of =<status>= when the mixer element is
+      off. Defaults to "[off]".
+    - Long option: =--off=
+
+  - =-C= /color/ On color
+
+    - The color to be used for =<status>= when the mixer element is on.
+      Defaults to "green".
+    - Long option: =--onc=
+
+  - =-c= /color/ Off color
+
+    - The color to be used for =<status>= when the mixer element is off.
+      Defaults to "red".
+    - Long option: =--offc=
+
+  - =--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.
+
+    - Long option: =--highv=
+
+  - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0.
+
+    - Long option: =--lowv=
+
+  - =-h=: /string/ High string
+
+    - 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=
+
+  - =-m=: /string/ Medium string
+
+    - 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=
+
+  - =-l=: /string/ Low string
+
+    - 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=
+
+- 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.
+
+** =Alsa Mixer Element Args=
+
+Like [[=Volume Mixer Element Args RefreshRate=][Volume]] but with the following differences:
+
+- 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=.
+
+** =MPD 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 =mpd=
+
+- 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:
+
+  - =lapsed-icon-pattern=: dynamic string for current track position in
+    =ipat=.
+
+- 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=
+
+- Default template: =MPD: <state>=
+
+- Example (note that you need "--" to separate regular monitor options
+  from MPD's specific ones):
+
+  #+begin_src haskell
+    Run MPD ["-t",
+             "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]",
+             "--", "-P", ">>", "-Z", "|", "-S", "><"] 10
+  #+end_src
+
+** =MPDX Args RefreshRate Alias=
+
+Like =MPD= but uses as alias its last argument instead of "mpd".
+
+** =Mpris1 PlayerName Args RefreshRate=
+
+- Aliases to =mpris1=
+
+- 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.
+
+- PlayerName: player supporting MPRIS v1 protocol. Some players need
+  this to be an all lowercase name (e.g. "spotify"), but some others
+  don't.
+
+- Args: default monitor arguments.
+
+- Variables that can be used with the =-t/--template= argument:
+  =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=
+
+- Default template: =<artist> - <title>=
+
+- Example:
+
+  #+begin_src haskell
+    Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10
+  #+end_src
+
+** =Mpris2 PlayerName Args RefreshRate=
+
+- Aliases to =mpris2=
+
+- 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.
+
+- PlayerName: player supporting MPRIS v2 protocol. Some players need
+  this to be an all lowercase name (e.g. "spotify"), but some others
+  don't.
+
+- Args: default monitor arguments.
+
+- Variables that can be used with the =-t/--template= argument:
+  =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=,
+  =composer=, =genre=
+
+- Default template: =<artist> - <title>=
+
+- Example:
+
+  #+begin_src haskell
+    Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10
+  #+end_src
+
+** =Mail Args Alias=
+
+- Args: list of maildirs in form =[("name1","path1"),...]=. Paths may
+  start with a '~' to expand to the user's home directory.
+
+- 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:
+
+  #+begin_src haskell
+    Run Mail [("inbox", "~/var/mail/inbox"),
+              ("lists", "~/var/mail/lists")]
+             "mail"
+  #+end_src
+
+** =MailX Args 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.
+
+- 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.
+
+- Example:
+
+  #+begin_src haskell
+    Run MailX [("I", "inbox", "green"),
+               ("L", "lists", "orange")]
+              ["-d", "~/var/mail", "-p", " ", "-s", " "]
+              "mail"
+  #+end_src
+
+** =MBox Mboxes Opts Alias=
+
+- 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:
+  -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
+
+- Paths may start with a '~' to expand to the user's home directory.
+
+- 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. 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
+    Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]
+             ["-d", "/var/mail/", "-p", " "] "mbox"
+  #+end_src
+
+** =NotmuchMail Alias Args Rate=
+
+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.
+
+- Alias: What name the plugin should have in your template string.
+
+- Args: A list of =MailItem= s of the form
+
+  #+begin_src haskell
+    [ MailItem "name" "address" "query"
+    ...
+    ]
+  #+end_src
+
+  or, using explicit record syntax:
+
+  #+begin_src haskell
+    [ MailItem
+        { name    = "name"
+        , address = "address"
+        , query   = "query"
+        }
+      ...
+    ]
+  #+end_src
+
+  where
+
+  - =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*.
+
+- Rate: Rate with which to update the plugin (in deciseconds).
+
+- Example:
+
+  - A single =MailItem= that displays all unread threads from the given
+    address:
+
+    #+begin_src haskell
+      MailItem "mbs:" "soliditsallgood@mailbox.org" ""
+    #+end_src
+
+  - A single =MailItem= that displays all unread threads with
+    "[My-Subject]" somewhere in the title:
+
+    #+begin_src haskell
+      MailItem "S:" "" "subject:[My-Subject]"
+    #+end_src
+
+  - A full example of a =NotmuchMail= configuration:
+
+    #+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"
+
+          -- All unread mail that has @[Haskell-Cafe]@ in the subject line.
+        , MailItem "C:" "" "subject:[Haskell-Cafe]"
+
+          -- 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
+
+** =XPropertyLog PropName=
+
+- 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.
+
+** =UnsafeXPropertyLog PropName=
+
+- 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.
+
+** =NamedXPropertyLog PropName Alias=
+
+- Aliases to =Alias=
+- Same as =XPropertyLog=, but a custom alias can be specified.
+
+** =UnsafeNamedXPropertyLog PropName Alias=
+
+- Aliases to =Alias=
+- Same as =UnsafeXPropertyLog=, but a custom alias can be specified.
+
+** =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:
+
+  #+begin_src haskell
+    Run Brightness ["-t", "<bar>"] 60
+  #+end_src
+
+** =Kbd Opts=
+
+- Registers to XKB/X11-Events and output the currently active keyboard
+  layout. Supports replacement of layout names.
+
+- Aliases to =kbd=
+
+- Opts is a list of tuples:
+
+  - first element of the tuple is the search string
+  - second element of the tuple is the corresponding replacement
+
+- Example:
+
+  #+begin_src haskell
+    Run Kbd [("us(dvorak)", "DV"), ("us", "US")]
+  #+end_src
+
+** =Locks=
+
+- Displays the status of Caps Lock, Num Lock and Scroll Lock.
+
+- Aliases to =locks=
+
+- Example:
+
+  #+begin_src haskell
+    Run Locks
+  #+end_src
+
+** =CatInt n filename=
+
+- Reads and displays an integer from the file whose path is =filename=
+  (especially useful with files in =/sys=).
+
+- Aliases as =catn= (e.g. =Cat 0= as =cat0=, etc.) so you can have
+  several.
+
+- Example:
+
+  #+begin_src haskell
+    Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50
+  #+end_src
+
+** =UVMeter=
+
+- Aliases to "uv" + station id. For example: =%uv Brisbane%= or
+  =%uv   Alice Springs%=
+
+- 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.
+
+    - Short option: =-m=
+    - Default: True
+
+- /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
+
+- Example:
+
+  #+begin_src haskell
+    Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
+  #+end_src
+
+* Interfacing with Window Managers
+
+Listed below are ways to interface xmobar with your window manager of
+choice.
+
+** =XMonadLog=
+
+- Aliases to XMonadLog
+
+- Displays information from xmonad's =_XMONAD_LOG=. You can use this by
+  using functions from the [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][XMonad.Hooks.DynamicLog]] module. By using the
+  =xmonadPropLog= function in your logHook, you can write the the above
+  property. The following shows a minimal xmonad configuration that
+  spawns xmobar and then writes to the =_XMONAD_LOG= property.
+
+  #+begin_src haskell
+    main = do
+      spawn "xmobar"
+      xmonad $ def
+        { logHook = dynamicLogString defaultPP >>= xmonadPropLog
+        }
+  #+end_src
+
+  This plugin can be used as a sometimes more convenient alternative to
+  =StdinReader=. For instance, it allows you to (re)start xmobar outside
+  xmonad.
+
+** =StdinReader=
+
+- Aliases to StdinReader
+- Displays any text received by xmobar on its standard input.
+- Strips actions from the text received. This means you can't pass
+  dynamic actions via stdin. This is safer than =UnsafeStdinReader=
+  because there is no need to escape the content before passing it to
+  xmobar's standard input.
+
+** =UnsafeStdinReader=
+
+- Aliases to UnsafeStdinReader
+- Displays any text received by xmobar on its standard input.
+- Will not do anything to the text received. This means you can pass
+  dynamic actions via stdin. Be careful to escape (using =<raw=…>=) or
+  remove tags from dynamic text that you pipe-thru to xmobar's standard
+  input, e.g. window's title.
+- Sample usage: send to xmobar's stdin the list of your workspaces
+  enclosed by actions tags that switches the workspaces to be able to
+  switch workspaces by clicking on xmobar:
+
+  #+begin_src shell
+    <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>
+  #+end_src
+
+** =UnsafeXMonadLog=
+
+- Aliases to UnsafeXMonadLog
+
+- Similar to =StdinReader= versus =UnsafeStdinReader=, this does not
+  strip =<action ...>= tags from XMonad's =_XMONAD_LOG=.
+
+- It is advised that you still use =xmobarStrip= for the ppTitle in your
+  logHook:
+
+  #+begin_src haskell
+    myPP = defaultPP { ppTitle = xmobarStrip }
+    main = xmonad $ def
+      { logHook = dynamicLogString myPP >>= xmonadPropLog
+      }
+  #+end_src
+
+** =CommandReader "/path/to/program" Alias=
+
+- Runs the given program, and displays its standard output.
+
+** =PipeReader "default text:/path/to/pipe" Alias=
+
+- Reads its displayed output from the given pipe.
+- Prefix an optional default text separated by a colon
+- Expands environment variables in the first argument of syntax =${VAR}=
+  or =$VAR=
+
+** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias=
+
+- Generally equivalent to PipeReader
+
+- Text is displayed as marquee with the specified length, rate in 10th
+  seconds and separator when it wraps around
+
+  #+begin_src haskell
+    Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"
+  #+end_src
+
+- Expands environment variables in the first argument
+
+** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]=
+
+- Display data from multiple pipes.
+
+- Timeout (in tenth of seconds) is the value after which the previous
+  content is restored i.e. if there was already something from a
+  previous pipe it will be put on display again, overwriting the current
+  status.
+
+- A pipe with Timeout of 0 will be displayed permanently, just like
+  =PipeReader=
+
+- The boolean option indicates whether new data for this pipe should
+  make xmobar appear (unhide, reveal). In this case, the Timeout
+  additionally specifies when the window should be hidden again. The
+  output is restored in any case.
+
+- Use it for OSD-like status bars e.g. for setting the volume or
+  brightness:
+
+  #+begin_src haskell
+    Run BufferedPipeReader "bpr"
+        [ (  0, False, "/tmp/xmobar_window"  )
+        , ( 15,  True, "/tmp/xmobar_status"  )
+        ]
+  #+end_src
+
+  Have your window manager send window titles to =/tmp/xmobar_window=.
+  They will always be shown and not reveal your xmobar. Sending some
+  status information to =/tmp/xmobar_status= will reveal xmonad for 1.5
+  seconds and temporarily overwrite the window titles.
+
+- Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]]
+
+- Expands environment variables for the pipe path
+
+** =HandleReader Handle Alias=
+
+- Display data from a Haskell =Handle=
+
+- This plugin is only useful if you are running xmobar from another
+  Haskell program like XMonad.
+
+- You can use =System.Process.createPipe= to create a pair of =read= &
+  =write= Handles. Pass the =read= Handle to HandleReader and write your
+  output to the =write= Handle:
+
+  #+begin_src haskell
+    (readHandle, writeHandle) <- createPipe
+    xmobarProcess <- forkProcess $ xmobar myConfig
+            { commands =
+                Run (HandleReader readHandle "handle") : commands myConfig
+            }
+    hPutStr writeHandle "Hello World"
+  #+end_src
+
+* Executing External Commands
+
+In order to execute an external command you can either write the command
+name in the template, in this case it will be executed without
+arguments, or you can configure it in the "commands" configuration
+option list with the Com template command:
+
+=Com ProgramName Args Alias RefreshRate=
+
+- ProgramName: the name of the program
+- Args: the arguments to be passed to the program at execution time
+- RefreshRate: number of tenths of second between re-runs of the
+  command. A zero or negative rate means that the command will be
+  executed only once.
+- Alias: a name to be used in the template. If the alias is en empty
+  string the program name can be used in the template.
+
+E.g.:
+
+#+begin_src haskell
+  Run Com "uname" ["-s","-r"] "" 0
+#+end_src
+
+can be used in the output template as =%uname%= (and xmobar will call
+/uname/ only once), while
+
+#+begin_src haskell
+  Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600
+#+end_src
+
+can be used in the output template as =%mydate%=.
+
+Sometimes, you don't mind if the command executed exits with an error,
+or you might want to display a custom message in that case. To that end,
+you can use the =ComX= variant:
+
+=ComX ProgramName Args ExitMessage Alias RefreshRate=
+
+Works like =Com=, but displaying =ExitMessage= (a string) if the
+execution fails. For instance:
+
+#+begin_src haskell
+  Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600
+#+end_src
+
+will display "N/A" if for some reason the =date= invocation fails.
+
+* The DBus Interface
+
+When compiled with the optional =with_dbus= flag, xmobar can be
+controlled over dbus. All signals defined in [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data
+SignalType= can now be sent over dbus to xmobar. Due to current
+limitations of the implementation only one process of xmobar can acquire
+the dbus. This is handled on a first-come-first-served basis, meaning
+that the first process will get the dbus interface. Other processes will
+run without further problems, yet have no dbus interface.
+
+- Bus Name: =org.Xmobar.Control=
+- Object Path: =/org/Xmobar/Control=
+- Member Name: Any of SignalType, e.g. =string:Reveal=
+- Interface Name: =org.Xmobar.Control=
+
+An example using the =dbus-send= command line utility:
+
+#+begin_src shell
+  dbus-send \
+      --session \
+      --dest=org.Xmobar.Control \
+      --type=method_call \
+      --print-reply \
+      '/org/Xmobar/Control' \
+      org.Xmobar.Control.SendSignal \
+      "string:Toggle 0"
+#+end_src
+
+It is also possible to send multiple signals at once:
+
+#+begin_src shell
+  # send to another screen, reveal and toggle the persistent flag
+  dbus-send [..] \
+      "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent"
+#+end_src
+
+The =Toggle=, =Reveal=, and =Hide= signals take an additional integer
+argument that denotes an initial delay, in tenths of a second, before
+the command takes effect.
+
+** Example for using the DBus IPC interface with XMonad
+
+Bind the key which should {,un}map xmobar to a dummy value. This is
+necessary for {,un}grabKey in xmonad.
+
+#+begin_src haskell
+  ((0, xK_Alt_L), pure ())
+#+end_src
+
+Also, install =avoidStruts= layout modifier from
+=XMonad.Hooks.ManageDocks=
+
+Finally, install these two event hooks (=handleEventHook= in =XConfig=)
+=myDocksEventHook= is a replacement for =docksEventHook= which reacts on
+unmap events as well (which =docksEventHook= doesn't).
+
+#+begin_src haskell
+  import qualified XMonad.Util.ExtensibleState as XS
+
+  data DockToggleTime = DTT { lastTime :: Time } deriving (Eq, Show, Typeable)
+
+  instance ExtensionClass DockToggleTime where
+      initialValue = DTT 0
+
+  toggleDocksHook :: Int -> KeySym -> Event -> X All
+  toggleDocksHook to ks ( KeyEvent { ev_event_display = d
+                                  , ev_event_type    = et
+                                  , ev_keycode       = ekc
+                                  , ev_time          = etime
+                                  } ) =
+          io (keysymToKeycode d ks) >>= toggleDocks >> return (All True)
+      where
+      toggleDocks kc
+          | ekc == kc && et == keyPress = do
+              safeSendSignal ["Reveal 0", "TogglePersistent"]
+              XS.put ( DTT etime )
+          | ekc == kc && et == keyRelease = do
+              gap <- XS.gets ( (-) etime . lastTime )
+              safeSendSignal [ "TogglePersistent"
+                          , "Hide " ++ show (if gap < 400 then to else 0)
+                          ]
+          | otherwise = return ()
+
+      safeSendSignal s = catchX (io $ sendSignal s) (return ())
+      sendSignal    = withSession . callSignal
+      withSession mc = connectSession >>= \c -> callNoReply c mc >> disconnect c
+      callSignal :: [String] -> MethodCall
+      callSignal s = ( methodCall
+                      ( objectPath_    "/org/Xmobar/Control" )
+                      ( interfaceName_ "org.Xmobar.Control"  )
+                      ( memberName_    "SendSignal"          )
+                  ) { methodCallDestination = Just $ busName_ "org.Xmobar.Control"
+                      , methodCallBody        = map toVariant s
+                      }
+
+  toggleDocksHook _ _ _ = return (All True)
+
+  myDocksEventHook :: Event -> X All
+  myDocksEventHook e = do
+      when (et == mapNotify || et == unmapNotify) $
+          whenX ((not `fmap` (isClient w)) <&&> runQuery checkDock w) refresh
+      return (All True)
+      where w  = ev_window e
+          et = ev_event_type e
+#+end_src
+
+* User plugins
+** Writing a Plugin
+
+Writing a plugin for xmobar should be very simple. You need to create a
+data type with at least one constructor.
+
+Next you must declare this data type an instance of the =Exec= class, by
+defining the 1 needed method (alternatively =start= or =run=) and 3
+optional ones (=alias=, =rate=, and =trigger=):
+
+#+begin_src haskell
+  start   :: e -> (String -> IO ()) -> IO ()
+  run     :: e -> IO String
+  rate    :: e -> Int
+  alias   :: e -> String
+  trigger :: e -> (Maybe SignalType -> IO ()) -> IO ()
+#+end_src
+
+=start= must receive a callback to be used to display the =String=
+produced by the plugin. This method can be used for plugins that need to
+perform asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for
+an example.
+
+=run= can be used for simpler plugins. If you define only =run= the
+plugin will be run every second. To overwrite this default you just need
+to implement =rate=, which must return the number of tenth of seconds
+between every successive runs. See [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of
+a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one
+that implements =rate=.
+
+Notice that Date could be implemented as:
+
+#+begin_src haskell
+  instance Exec Date where
+      alias (Date _ a _) = a
+      start (Date f _ r) = date f r
+
+  date :: String -> Int -> (String -> IO ()) -> IO ()
+  date format r callback = do go
+      where go = do
+              t <- toCalendarTime =<< getClockTime
+              callback $ formatCalendarTime defaultTimeLocale format t
+              tenthSeconds r >> go
+#+end_src
+
+This implementation is equivalent to the one you can read in
+=Plugins/Date.hs=.
+
+=alias= is the name to be used in the output template. Default alias
+will be the data type constructor.
+
+After that your type constructor can be used as an argument for the
+Runnable type constructor =Run= in the =commands= list of the
+configuration options.
+
+** Using a Plugin
+
+To use your new plugin, you need to use a pure Haskell configuration for
+xmobar, and load your definitions there. You can see an example in
+[[./examples/xmobar.hs][examples/xmobar.hs]] showing you how to write a Haskell configuration that
+uses a new plugin, all in one file.
+
+When xmobar runs with the full path to that Haskell file as its argument
+(or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar
+library installed (e.g., with =cabal install --lib xmobar=), the Haskell
+code will be compiled as needed, and the new executable spawned for you.
+
+That's it!
+
+** Configurations written in pure Haskell
+
+xmobar can be used as a pure Haskell program, that is compiled with your
+specific configuration, expressed as Haskell source code. For an
+example, see [[https://gitlab.com/jaor/xmobar-config/][the author's configuration]].
diff --git a/readme.org b/readme.org
index b0f3f58..0d95a25 100644
--- a/readme.org
+++ b/readme.org
@@ -180,7 +180,6 @@ Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:
   screen.
 
 * Configuration
-
 ** Quick Start
 
 See [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][examples/xmobar.config]] for an example.
@@ -526,1617 +525,6 @@ much more: we list all available plugins below.
 Other commands can be created as plugins with the Plugin infrastructure.
 See below.
 
-* System Monitor Plugins
-
-This is the description of the system monitor plugins available in
-xmobar. Some of them are only installed when an optional build option is
-set: we mention that fact, when needed, in their description.
-
-Each monitor has an =alias= to be used in the output template. 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.
-
-** 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
-(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,
-
-#+begin_src haskell
-  Run Brightness
-    [ "-t", "<ipat>"
-    , "--"
-    , "--brightness-icon-pattern", "<icon=bright_%%.xpm/>"
-    ] 30
-#+end_src
-
-Will display =bright_0.xpm= to =bright_8.xpm= depending on current
-brightness value.
-
-** Default Monitor Arguments
-
-Monitors accept a common set of arguments, described in the first
-subsection below. In addition, some monitors accept additional options
-that are specific to them. When specifying the list of arguments in your
-configuration, the common options come first, followed by =--=, followed
-by any monitor-specific options.
-
-These are the options available for all monitors below:
-
-- =-t= /string/ Output template
-
-  - Template for the monitor output. Field names must be enclosed
-    between pointy brackets (=<foo>=) and will be substituted by the
-    computed values. You can also specify the foreground (and
-    optionally, background) color for a region by bracketing it between
-    =<fc=fgcolor>= (or =<fc=fgcolor,bgcolor>=) and =</fc>=. The rest of
-    the template is output verbatim.
-  - Long option: =--template=
-  - Default value: per monitor (see above).
-
-- =-H= /number/ The high threshold.
-
-  - Numerical values higher than /number/ will be displayed with the
-    color specified by =-h= (see below).
-  - Long option: =--High=
-  - Default value: 66
-
-- =-L= /number/ The low threshold.
-
-  - Numerical values higher than /number/ and lower than the high
-    threshold will be displayed with the color specified by =-n= (see
-    below). Values lower than /number/ will use the =-l= color.
-  - Long option: =--Low=
-  - Default value: 33
-
-- =-h= /color/ High threshold color.
-
-  - Color for displaying values above the high threshold. /color/ can be
-    either a name (e.g. "blue") or an hexadecimal RGB (e.g. "#FF0000").
-  - Long option: =--high=
-  - Default: none (use the default foreground).
-
-- =-n= /color/ Color for 'normal' values
-
-  - Color used for values greater than the low threshold but lower than
-    the high one.
-  - Long option: =--normal=
-  - Default: none (use the default foreground).
-
-- =-l= /color/ The low threshold color
-
-  - Color for displaying values below the low threshold.
-  - Long option: =--low=
-  - Default: none (use the default foreground).
-
-- =-S= /boolean/ Display optional suffixes
-
-  - When set to a true designator ("True", "Yes" or "On"), optional
-    value suffixes such as the '%' symbol or optional units will be
-    displayed.
-  - Long option: =--suffix=
-  - Default: False.
-
-- =-p= /number/ Percentages padding
-
-  - Width, in number of digits, for quantities representing percentages.
-    For instance =-p 3= means that all percentages in the monitor will
-    be represented using 3 digits.
-  - Long option: =--ppad=
-  - Default value: 0 (don't pad)
-
-- =-d= /number/ Decimal digits
-
-  - Number of digits after the decimal period to use in float values.
-  - Long option: =--ddigits=
-  - Default value: 0 (display only integer part)
-
-- =-m= /number/ Minimum field width
-
-  - Minimum width, in number of characters, of the fields in the monitor
-    template. Values whose printed representation is shorter than this
-    value will be padded using the padding characters given by the =-c=
-    option with the alignment specified by =-a= (see below).
-  - Long option: =--minwidth=
-  - Default: 0
-
-- =-M= /number/ Maximum field width
-
-  - Maximum width, in number of characters, of the fields in the monitor
-    template. Values whose printed representation is longer than this
-    value will be truncated.
-  - Long option: =--maxwidth=
-  - Default: 0 (no maximum width)
-
-- =-e= /string/ Maximum width ellipsis
-
-  - Ellipsis to be added to the field when it has reached its max width.
-  - Long option: =--maxwidthellipsis=
-  - Default: "" (no ellipsis)
-
-- =-w= /number/ Fixed field width
-
-  - All fields will be set to this width, padding or truncating as
-    needed.
-  - Long option: =--width=
-  - Default: 0 (variable width)
-
-- =-T= /number/ Maximum total width
-
-  - Maximum total width of the text.
-  - Long option: =--maxtwidth=
-  - Default: 0 (no limit)
-
-- =-E= /string/ Maximum total width ellipsis
-
-  - Ellipsis to be added to the total text when it has reached its max
-    width.
-  - Long option: =--maxtwidthellipsis=
-  - Default: "" (no ellipsis)
-
-- =-c= /string/
-
-  - Characters used for padding. The characters of /string/ are used
-    cyclically. E.g., with =-P +- -w 6=, a field with value "foo" will
-    be represented as "+-+foo".
-  - Long option: =--padchars=
-  - Default value: " "
-
-- =-a= r|l Field alignment
-
-  - Whether to use right (r) or left (l) alignment of field values when
-    padding.
-  - Long option: =--align=
-  - Default value: r (padding to the left)
-
-- =-b= /string/ Bar background
-
-  - Characters used, cyclically, to draw the background of bars. For
-    instance, if you set this option to "·.", an empty bar will look
-    like this: =·.·.·.·.·.=
-  - Long option: =--bback=
-  - Default value: ":"
-
-- =-f= /string/ Bar foreground
-
-  - Characters used, cyclically, to draw the foreground of bars.
-  - Long option: =--bfore=
-  - Default value: "#"
-
-- =-W= /number/ Bar width
-
-  - Total number of characters used to draw bars.
-  - Long option: =--bwidth=
-  - Default value: 10
-  - Special value: 0. When this parameter is 0, the percentage to
-    display is interpreted as a position in the bar foreground string
-    (given by =-f=), and the character at that position is displayed.
-
-- =-x= /string/ N/A string
-
-  - String to be used when the monitor is not available
-  - Long option: =--nastring=
-  - Default value: "N/A"
-
-Commands' arguments must be set as a list. E.g.:
-
-#+begin_src haskell
-  Run Weather "EGPF" ["-t", "<station>: <tempC>C"] 36000
-#+end_src
-
-In this case xmobar will run the weather monitor, getting information
-for the weather station ID EGPF (Glasgow Airport, as a homage to GHC)
-every hour (36000 tenth of seconds), with a template that will output
-something like:
-
-#+begin_src shell
-  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.
-
-** =DiskU Disks Args RefreshRate=
-
-- 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>=, =<freeipat>=, =<usedbar>=,
-  =<usedvbar>= or =<usedipat>= for total, free, used, free percentage
-  and used percentage of the given file system capacity.
-
-- Thresholds refer to usage percentage.
-
-- Args: default monitor arguments. =-t/--template= is ignored. Plus
-
-  - =--free-icon-pattern=: dynamic string for free disk space in
-    =freeipat=.
-  - =--used-icon-pattern=: dynamic string for used disk space in
-    =usedipat=.
-
-- Default template: none (you must specify a template for each file
-  system).
-
-- Example:
-
-  #+begin_src haskell
-    DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")]
-          ["-L", "20", "-H", "50", "-m", "1", "-p", "3"]
-          20
-  #+end_src
-
-** =DiskIO Disks Args RefreshRate=
-
-- Aliases to =diskio=
-
-- 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>=.
-
-- Thresholds refer to speed in b/s
-
-- Args: default monitor arguments. =-t/--template= is ignored. Plus
-
-  - =--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>=.
-
-- Default template: none (you must specify a template for each file
-  system).
-
-- Example:
-
-  #+begin_src haskell
-    DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10
-  #+end_src
-
-** =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:
-
-  #+begin_src haskell
-    Run ThermalZone 0 ["-t","<id>: <temp>C"] 30
-  #+end_src
-
-** =Thermal Zone Args RefreshRate=
-
-- *This plugin is deprecated. Use =ThermalZone= instead.*
-
-- Aliases to the Zone: so =Thermal "THRM" []= can be used in template as
-  =%THRM%=
-
-- Args: default monitor arguments
-
-- Thresholds refer to temperature in degrees
-
-- Variables that can be used with the =-t/--template= argument: =temp=
-
-- Default template: =Thm: <temp>C=
-
-- This plugin works only on systems with devices having thermal zone.
-  Check directories in /proc/acpi/thermal_zone for possible values.
-
-- Example:
-
-  #+begin_src haskell
-    Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50
-  #+end_src
-
-** =CpuFreq Args RefreshRate=
-
-- Aliases to =cpufreq=
-
-- Args: default monitor arguments
-
-- Thresholds refer to frequency in GHz
-
-- Variables that can be used with the =-t/--template= argument:
-  =cpu0=, =cpu1=, .., =cpuN=
-
-- Default template: =Freq: <cpu0>GHz=
-
-- This monitor requires acpi_cpufreq module to be loaded in kernel
-
-- Example:
-
-  #+begin_src haskell
-    Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",
-                 "-l", "lightblue", "-n","white", "-h", "red"] 50
-  #+end_src
-
-** =CoreTemp Args RefreshRate=
-
-- Aliases to =coretemp=
-
-- Args: default monitor arguments
-
-- Thresholds refer to temperature in degrees
-
-- Variables that can be used with the =-t/--template= argument:
-  =core0=, =core1=, .., =coreN=
-
-- Default template: =Temp: <core0>C=
-
-- This monitor requires coretemp module to be loaded in kernel
-
-- Example:
-
-  #+begin_src haskell
-    Run CoreTemp ["-t", "Temp:<core0>|<core1>C",
-                  "-L", "40", "-H", "60",
-                  "-l", "lightblue", "-n", "gray90", "-h", "red"] 50
-  #+end_src
-
-** =MultiCoreTemp Args RefreshRate=
-
-- Aliases to =multicoretemp=
-
-- Args: default monitor arguments, plus:
-
-  - =--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.
-
-- Thresholds refer to temperature in degree Celsius
-
-- Variables that can be used with the =-t/--template= argument: =max=,
-  =maxpc=, =maxbar=, =maxvbar=, =maxipat=, =avg=, =avgpc=, =avgbar=,
-  =avgvbar=, =avgipat=, =core0=, =core1=, ..., =coreN=
-
-  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.
-
-- Default template: =Temp: <max>°C - <maxpc>%=
-
-- This monitor requires coretemp module to be loaded in kernel
-
-- Example:
-
-  #+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
-
-** =Volume Mixer Element Args RefreshRate=
-
-- 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:
-
-  - =-O= /string/ On string
-
-    - The string used in place of =<status>= when the mixer element is
-      on. Defaults to "[on]".
-    - Long option: =--on=
-
-  - =-o= /string/ Off string
-
-    - The string used in place of =<status>= when the mixer element is
-      off. Defaults to "[off]".
-    - Long option: =--off=
-
-  - =-C= /color/ On color
-
-    - The color to be used for =<status>= when the mixer element is on.
-      Defaults to "green".
-    - Long option: =--onc=
-
-  - =-c= /color/ Off color
-
-    - The color to be used for =<status>= when the mixer element is off.
-      Defaults to "red".
-    - Long option: =--offc=
-
-  - =--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.
-
-    - Long option: =--highv=
-
-  - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0.
-
-    - Long option: =--lowv=
-
-  - =-h=: /string/ High string
-
-    - 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=
-
-  - =-m=: /string/ Medium string
-
-    - 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=
-
-  - =-l=: /string/ Low string
-
-    - 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=
-
-- 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.
-
-** =Alsa Mixer Element Args=
-
-Like [[=Volume Mixer Element Args RefreshRate=][Volume]] but with the following differences:
-
-- 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=.
-
-** =MPD 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 =mpd=
-
-- 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:
-
-  - =lapsed-icon-pattern=: dynamic string for current track position in
-    =ipat=.
-
-- 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=
-
-- Default template: =MPD: <state>=
-
-- Example (note that you need "--" to separate regular monitor options
-  from MPD's specific ones):
-
-  #+begin_src haskell
-    Run MPD ["-t",
-             "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]",
-             "--", "-P", ">>", "-Z", "|", "-S", "><"] 10
-  #+end_src
-
-** =MPDX Args RefreshRate Alias=
-
-Like =MPD= but uses as alias its last argument instead of "mpd".
-
-** =Mpris1 PlayerName Args RefreshRate=
-
-- Aliases to =mpris1=
-
-- 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.
-
-- PlayerName: player supporting MPRIS v1 protocol. Some players need
-  this to be an all lowercase name (e.g. "spotify"), but some others
-  don't.
-
-- Args: default monitor arguments.
-
-- Variables that can be used with the =-t/--template= argument:
-  =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=
-
-- Default template: =<artist> - <title>=
-
-- Example:
-
-  #+begin_src haskell
-    Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10
-  #+end_src
-
-** =Mpris2 PlayerName Args RefreshRate=
-
-- Aliases to =mpris2=
-
-- 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.
-
-- PlayerName: player supporting MPRIS v2 protocol. Some players need
-  this to be an all lowercase name (e.g. "spotify"), but some others
-  don't.
-
-- Args: default monitor arguments.
-
-- Variables that can be used with the =-t/--template= argument:
-  =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=,
-  =composer=, =genre=
-
-- Default template: =<artist> - <title>=
-
-- Example:
-
-  #+begin_src haskell
-    Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10
-  #+end_src
-
-** =Mail Args Alias=
-
-- Args: list of maildirs in form =[("name1","path1"),...]=. Paths may
-  start with a '~' to expand to the user's home directory.
-
-- 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:
-
-  #+begin_src haskell
-    Run Mail [("inbox", "~/var/mail/inbox"),
-              ("lists", "~/var/mail/lists")]
-             "mail"
-  #+end_src
-
-** =MailX Args 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.
-
-- 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.
-
-- Example:
-
-  #+begin_src haskell
-    Run MailX [("I", "inbox", "green"),
-               ("L", "lists", "orange")]
-              ["-d", "~/var/mail", "-p", " ", "-s", " "]
-              "mail"
-  #+end_src
-
-** =MBox Mboxes Opts Alias=
-
-- 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:
-  -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
-
-- Paths may start with a '~' to expand to the user's home directory.
-
-- 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. 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
-    Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]
-             ["-d", "/var/mail/", "-p", " "] "mbox"
-  #+end_src
-
-** =NotmuchMail Alias Args Rate=
-
-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.
-
-- Alias: What name the plugin should have in your template string.
-
-- Args: A list of =MailItem= s of the form
-
-  #+begin_src haskell
-    [ MailItem "name" "address" "query"
-    ...
-    ]
-  #+end_src
-
-  or, using explicit record syntax:
-
-  #+begin_src haskell
-    [ MailItem
-        { name    = "name"
-        , address = "address"
-        , query   = "query"
-        }
-      ...
-    ]
-  #+end_src
-
-  where
-
-  - =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*.
-
-- Rate: Rate with which to update the plugin (in deciseconds).
-
-- Example:
-
-  - A single =MailItem= that displays all unread threads from the given
-    address:
-
-    #+begin_src haskell
-      MailItem "mbs:" "soliditsallgood@mailbox.org" ""
-    #+end_src
-
-  - A single =MailItem= that displays all unread threads with
-    "[My-Subject]" somewhere in the title:
-
-    #+begin_src haskell
-      MailItem "S:" "" "subject:[My-Subject]"
-    #+end_src
-
-  - A full example of a =NotmuchMail= configuration:
-
-    #+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"
-
-          -- All unread mail that has @[Haskell-Cafe]@ in the subject line.
-        , MailItem "C:" "" "subject:[Haskell-Cafe]"
-
-          -- 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
-
-** =XPropertyLog PropName=
-
-- 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.
-
-** =UnsafeXPropertyLog PropName=
-
-- 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.
-
-** =NamedXPropertyLog PropName Alias=
-
-- Aliases to =Alias=
-- Same as =XPropertyLog=, but a custom alias can be specified.
-
-** =UnsafeNamedXPropertyLog PropName Alias=
-
-- Aliases to =Alias=
-- Same as =UnsafeXPropertyLog=, but a custom alias can be specified.
-
-** =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:
-
-  #+begin_src haskell
-    Run Brightness ["-t", "<bar>"] 60
-  #+end_src
-
-** =Kbd Opts=
-
-- Registers to XKB/X11-Events and output the currently active keyboard
-  layout. Supports replacement of layout names.
-
-- Aliases to =kbd=
-
-- Opts is a list of tuples:
-
-  - first element of the tuple is the search string
-  - second element of the tuple is the corresponding replacement
-
-- Example:
-
-  #+begin_src haskell
-    Run Kbd [("us(dvorak)", "DV"), ("us", "US")]
-  #+end_src
-
-** =Locks=
-
-- Displays the status of Caps Lock, Num Lock and Scroll Lock.
-
-- Aliases to =locks=
-
-- Example:
-
-  #+begin_src haskell
-    Run Locks
-  #+end_src
-
-** =CatInt n filename=
-
-- Reads and displays an integer from the file whose path is =filename=
-  (especially useful with files in =/sys=).
-
-- Aliases as =catn= (e.g. =Cat 0= as =cat0=, etc.) so you can have
-  several.
-
-- Example:
-
-  #+begin_src haskell
-    Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50
-  #+end_src
-
-** =UVMeter=
-
-- Aliases to "uv" + station id. For example: =%uv Brisbane%= or
-  =%uv   Alice Springs%=
-
-- 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.
-
-    - Short option: =-m=
-    - Default: True
-
-- /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
-
-- Example:
-
-  #+begin_src haskell
-    Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
-  #+end_src
-
-* Executing External Commands
-
-In order to execute an external command you can either write the command
-name in the template, in this case it will be executed without
-arguments, or you can configure it in the "commands" configuration
-option list with the Com template command:
-
-=Com ProgramName Args Alias RefreshRate=
-
-- ProgramName: the name of the program
-- Args: the arguments to be passed to the program at execution time
-- RefreshRate: number of tenths of second between re-runs of the
-  command. A zero or negative rate means that the command will be
-  executed only once.
-- Alias: a name to be used in the template. If the alias is en empty
-  string the program name can be used in the template.
-
-E.g.:
-
-#+begin_src haskell
-  Run Com "uname" ["-s","-r"] "" 0
-#+end_src
-
-can be used in the output template as =%uname%= (and xmobar will call
-/uname/ only once), while
-
-#+begin_src haskell
-  Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600
-#+end_src
-
-can be used in the output template as =%mydate%=.
-
-Sometimes, you don't mind if the command executed exits with an error,
-or you might want to display a custom message in that case. To that end,
-you can use the =ComX= variant:
-
-=ComX ProgramName Args ExitMessage Alias RefreshRate=
-
-Works like =Com=, but displaying =ExitMessage= (a string) if the
-execution fails. For instance:
-
-#+begin_src haskell
-  Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600
-#+end_src
-
-will display "N/A" if for some reason the =date= invocation fails.
-
-* Other Plugins
-
-** =StdinReader=
-
-- Aliases to StdinReader
-- Displays any text received by xmobar on its standard input.
-- Strips actions from the text received. This means you can't pass
-  dynamic actions via stdin. This is safer than =UnsafeStdinReader=
-  because there is no need to escape the content before passing it to
-  xmobar's standard input.
-
-** =UnsafeStdinReader=
-
-- Aliases to UnsafeStdinReader
-- Displays any text received by xmobar on its standard input.
-- Will not do anything to the text received. This means you can pass
-  dynamic actions via stdin. Be careful to escape (using =<raw=…>=) or
-  remove tags from dynamic text that you pipe-thru to xmobar's standard
-  input, e.g. window's title.
-- Sample usage: send to xmobar's stdin the list of your workspaces
-  enclosed by actions tags that switches the workspaces to be able to
-  switch workspaces by clicking on xmobar:
-
-  #+begin_src shell
-    <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>
-  #+end_src
-
-** =Date Format Alias RefreshRate=
-
-- Format is a time format string, as accepted by the standard ISO C
-  =strftime= function (or Haskell's =formatCalendarTime=).
-
-- 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=
-
-- Format is a time format string, as accepted by the standard ISO C
-  =strftime= function (or Haskell's =formatCalendarTime=).
-
-- If Locale is "" the default locale of the system is used, otherwise
-  the given locale. If there are more instances of DateZone, using "" as
-  input for Locale is not recommended.
-
-- Zone is the name of the TimeZone. It is assumed that the tz database
-  is stored in =/usr/share/zoneinfo/=. If "" 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
-
-** =CommandReader "/path/to/program" Alias=
-
-- Runs the given program, and displays its standard output.
-
-** =PipeReader "default text:/path/to/pipe" Alias=
-
-- Reads its displayed output from the given pipe.
-- Prefix an optional default text separated by a colon
-- Expands environment variables in the first argument of syntax =${VAR}=
-  or =$VAR=
-
-** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias=
-
-- Generally equivalent to PipeReader
-
-- Text is displayed as marquee with the specified length, rate in 10th
-  seconds and separator when it wraps around
-
-  #+begin_src haskell
-    Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"
-  #+end_src
-
-- Expands environment variables in the first argument
-
-** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]=
-
-- Display data from multiple pipes.
-
-- Timeout (in tenth of seconds) is the value after which the previous
-  content is restored i.e. if there was already something from a
-  previous pipe it will be put on display again, overwriting the current
-  status.
-
-- A pipe with Timeout of 0 will be displayed permanently, just like
-  =PipeReader=
-
-- The boolean option indicates whether new data for this pipe should
-  make xmobar appear (unhide, reveal). In this case, the Timeout
-  additionally specifies when the window should be hidden again. The
-  output is restored in any case.
-
-- Use it for OSD-like status bars e.g. for setting the volume or
-  brightness:
-
-  #+begin_src haskell
-    Run BufferedPipeReader "bpr"
-        [ (  0, False, "/tmp/xmobar_window"  )
-        , ( 15,  True, "/tmp/xmobar_status"  )
-        ]
-  #+end_src
-
-  Have your window manager send window titles to =/tmp/xmobar_window=.
-  They will always be shown and not reveal your xmobar. Sending some
-  status information to =/tmp/xmobar_status= will reveal xmonad for 1.5
-  seconds and temporarily overwrite the window titles.
-
-- Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]]
-
-- Expands environment variables for the pipe path
-
-** =XMonadLog=
-
-- Aliases to XMonadLog
-
-- Displays information from xmonad's =_XMONAD_LOG=. You can set this
-  property by using =xmonadPropLog= as your log hook in xmonad's
-  configuration, as in the following example (more info [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][here]]):
-
-  #+begin_src haskell
-    main = do
-      spawn "xmobar"
-      xmonad $ def
-        { logHook = dynamicLogString defaultPP >>= xmonadPropLog
-        }
-  #+end_src
-
-  This plugin can be used as a sometimes more convenient alternative to
-  =StdinReader=. For instance, it allows you to (re)start xmobar outside
-  xmonad.
-
-** =UnsafeXMonadLog=
-
-- Aliases to UnsafeXMonadLog
-
-- Similar to StdinReader versus UnsafeStdinReader, this does not strip
-  =<action   ...>= tags from XMonad's =_XMONAD_LOG=.
-
-- It is advised that you still use =xmobarStrip= for the ppTitle in your
-  logHook:
-
-  #+begin_src haskell
-    myPP = defaultPP { ppTitle = xmobarStrip }
-    main = xmonad $ def
-      { logHook = dynamicLogString myPP >>= xmonadPropLog
-      }
-  #+end_src
-
-** =HandleReader Handle Alias=
-
-- Display data from a Haskell =Handle=
-
-- This plugin is only useful if you are running xmobar from another
-  Haskell program like XMonad.
-
-- You can use =System.Process.createPipe= to create a pair of =read= &
-  =write= Handles. Pass the =read= Handle to HandleReader and write your
-  output to the =write= Handle:
-
-  #+begin_src haskell
-    (readHandle, writeHandle) <- createPipe
-    xmobarProcess <- forkProcess $ xmobar myConfig
-            { commands =
-                Run (HandleReader readHandle "handle") : commands myConfig
-            }
-    hPutStr writeHandle "Hello World"
-  #+end_src
-
-* The DBus Interface
-
-When compiled with the optional =with_dbus= flag, xmobar can be
-controlled over dbus. All signals defined in [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data
-SignalType= can now be sent over dbus to xmobar. Due to current
-limitations of the implementation only one process of xmobar can acquire
-the dbus. This is handled on a first-come-first-served basis, meaning
-that the first process will get the dbus interface. Other processes will
-run without further problems, yet have no dbus interface.
-
-- Bus Name: =org.Xmobar.Control=
-- Object Path: =/org/Xmobar/Control=
-- Member Name: Any of SignalType, e.g. =string:Reveal=
-- Interface Name: =org.Xmobar.Control=
-
-An example using the =dbus-send= command line utility:
-
-#+begin_src shell
-  dbus-send \
-      --session \
-      --dest=org.Xmobar.Control \
-      --type=method_call \
-      --print-reply \
-      '/org/Xmobar/Control' \
-      org.Xmobar.Control.SendSignal \
-      "string:Toggle 0"
-#+end_src
-
-It is also possible to send multiple signals at once:
-
-#+begin_src shell
-  # send to another screen, reveal and toggle the persistent flag
-  dbus-send [..] \
-      "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent"
-#+end_src
-
-The =Toggle=, =Reveal=, and =Hide= signals take an additional integer
-argument that denotes an initial delay, in tenths of a second, before
-the command takes effect.
-
-** Example for using the DBus IPC interface with XMonad
-
-Bind the key which should {,un}map xmobar to a dummy value. This is
-necessary for {,un}grabKey in xmonad.
-
-#+begin_src haskell
-  ((0, xK_Alt_L), pure ())
-#+end_src
-
-Also, install =avoidStruts= layout modifier from
-=XMonad.Hooks.ManageDocks=
-
-Finally, install these two event hooks (=handleEventHook= in =XConfig=)
-=myDocksEventHook= is a replacement for =docksEventHook= which reacts on
-unmap events as well (which =docksEventHook= doesn't).
-
-#+begin_src haskell
-  import qualified XMonad.Util.ExtensibleState as XS
-
-  data DockToggleTime = DTT { lastTime :: Time } deriving (Eq, Show, Typeable)
-
-  instance ExtensionClass DockToggleTime where
-      initialValue = DTT 0
-
-  toggleDocksHook :: Int -> KeySym -> Event -> X All
-  toggleDocksHook to ks ( KeyEvent { ev_event_display = d
-                                  , ev_event_type    = et
-                                  , ev_keycode       = ekc
-                                  , ev_time          = etime
-                                  } ) =
-          io (keysymToKeycode d ks) >>= toggleDocks >> return (All True)
-      where
-      toggleDocks kc
-          | ekc == kc && et == keyPress = do
-              safeSendSignal ["Reveal 0", "TogglePersistent"]
-              XS.put ( DTT etime )
-          | ekc == kc && et == keyRelease = do
-              gap <- XS.gets ( (-) etime . lastTime )
-              safeSendSignal [ "TogglePersistent"
-                          , "Hide " ++ show (if gap < 400 then to else 0)
-                          ]
-          | otherwise = return ()
-
-      safeSendSignal s = catchX (io $ sendSignal s) (return ())
-      sendSignal    = withSession . callSignal
-      withSession mc = connectSession >>= \c -> callNoReply c mc >> disconnect c
-      callSignal :: [String] -> MethodCall
-      callSignal s = ( methodCall
-                      ( objectPath_    "/org/Xmobar/Control" )
-                      ( interfaceName_ "org.Xmobar.Control"  )
-                      ( memberName_    "SendSignal"          )
-                  ) { methodCallDestination = Just $ busName_ "org.Xmobar.Control"
-                      , methodCallBody        = map toVariant s
-                      }
-
-  toggleDocksHook _ _ _ = return (All True)
-
-  myDocksEventHook :: Event -> X All
-  myDocksEventHook e = do
-      when (et == mapNotify || et == unmapNotify) $
-          whenX ((not `fmap` (isClient w)) <&&> runQuery checkDock w) refresh
-      return (All True)
-      where w  = ev_window e
-          et = ev_event_type e
-#+end_src
-
-* User plugins
-
-** Writing a Plugin
-
-Writing a plugin for xmobar should be very simple. You need to create a
-data type with at least one constructor.
-
-Next you must declare this data type an instance of the =Exec= class, by
-defining the 1 needed method (alternatively =start= or =run=) and 3
-optional ones (=alias=, =rate=, and =trigger=):
-
-#+begin_src haskell
-  start   :: e -> (String -> IO ()) -> IO ()
-  run     :: e -> IO String
-  rate    :: e -> Int
-  alias   :: e -> String
-  trigger :: e -> (Maybe SignalType -> IO ()) -> IO ()
-#+end_src
-
-=start= must receive a callback to be used to display the =String=
-produced by the plugin. This method can be used for plugins that need to
-perform asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for
-an example.
-
-=run= can be used for simpler plugins. If you define only =run= the
-plugin will be run every second. To overwrite this default you just need
-to implement =rate=, which must return the number of tenth of seconds
-between every successive runs. See [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of
-a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one
-that implements =rate=.
-
-Notice that Date could be implemented as:
-
-#+begin_src haskell
-  instance Exec Date where
-      alias (Date _ a _) = a
-      start (Date f _ r) = date f r
-
-  date :: String -> Int -> (String -> IO ()) -> IO ()
-  date format r callback = do go
-      where go = do
-              t <- toCalendarTime =<< getClockTime
-              callback $ formatCalendarTime defaultTimeLocale format t
-              tenthSeconds r >> go
-#+end_src
-
-This implementation is equivalent to the one you can read in
-=Plugins/Date.hs=.
-
-=alias= is the name to be used in the output template. Default alias
-will be the data type constructor.
-
-After that your type constructor can be used as an argument for the
-Runnable type constructor =Run= in the =commands= list of the
-configuration options.
-
-** Using a Plugin
-
-To use your new plugin, you need to use a pure Haskell configuration for
-xmobar, and load your definitions there. You can see an example in
-[[./examples/xmobar.hs][examples/xmobar.hs]] showing you how to write a Haskell configuration that
-uses a new plugin, all in one file.
-
-When xmobar runs with the full path to that Haskell file as its argument
-(or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar
-library installed (e.g., with =cabal install --lib xmobar=), the Haskell
-code will be compiled as needed, and the new executable spawned for you.
-
-That's it!
-
-** Configurations written in pure Haskell
-
-xmobar can be used as a pure Haskell program, that is compiled with your
-specific configuration, expressed as Haskell source code. For an
-example, see [[https://gitlab.com/jaor/xmobar-config/][the author's configuration]].
-
 * Authors and credits
 
 Andrea Rossato originally designed and implemented xmobar up to version