Convert readme to org-mode

2 files changed, 2183 insertions, 2087 deletions

diff --git a/readme.md b/readme.md
deleted file mode 100644
index 8a7f322..0000000
--- a/readme.md
+++ /dev/null
@@ -1,2087 +0,0 @@
-[![Hackage](https://img.shields.io/hackage/v/xmobar.svg)](http://hackage.haskell.org/package/xmobar)
-
-<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
-**Table of Contents**
-
-- [About](#about)
-- [Installation](#installation)
-    - [Using cabal-install](#using-cabal-install)
-    - [From source](#from-source)
-    - [Optional features](#optional-features)
-- [Running xmobar](#running-xmobar)
-    - [Signal Handling](#signal-handling)
-- [Configuration](#configuration)
-    - [Quick Start](#quick-start)
-        - [Running xmobar with i3status](#running-xmobar-with-i3status)
-        - [Dynamically sizing xmobar](#dynamically-sizing-xmobar)
-    - [Command Line Options](#command-line-options)
-    - [The Output Template](#the-output-template)
-    - [The `commands` Configuration Option](#the-commands-configuration-option)
-- [System Monitor Plugins](#system-monitor-plugins)
-    - [Icon patterns](#icon-patterns)
-    - [Default Monitor Arguments](#default-monitor-arguments)
-    - [`Uptime Args RefreshRate`](#uptime-args-refreshrate)
-    - [`Weather StationID Args RefreshRate`](#weather-stationid-args-refreshrate)
-    - [`WeatherX StationID SkyConditions Args RefreshRate`](#weatherx-stationid-skyconditions-args-refreshrate)
-    - [`Network Interface Args RefreshRate`](#network-interface-args-refreshrate)
-    - [`DynNetwork Args RefreshRate`](#dynnetwork-args-refreshrate)
-    - [`Wireless Interface Args RefreshRate`](#wireless-interface-args-refreshrate)
-    - [`Memory Args RefreshRate`](#memory-args-refreshrate)
-    - [`Swap Args RefreshRate`](#swap-args-refreshrate)
-    - [`Cpu Args RefreshRate`](#cpu-args-refreshrate)
-    - [`MultiCpu Args RefreshRate`](#multicpu-args-refreshrate)
-    - [`Battery Args RefreshRate`](#battery-args-refreshrate)
-    - [`BatteryP Dirs Args RefreshRate`](#batteryp-dirs-args-refreshrate)
-    - [`BatteryN Dirs Args RefreshRate Alias`](#batteryn-dirs-args-refreshrate-alias)
-    - [`TopProc Args RefreshRate`](#topproc-args-refreshrate)
-    - [`TopMem Args RefreshRate`](#topmem-args-refreshrate)
-    - [`DiskU Disks Args RefreshRate`](#disku-disks-args-refreshrate)
-    - [`DiskIO Disks Args RefreshRate`](#diskio-disks-args-refreshrate)
-    - [`ThermalZone Number Args RefreshRate`](#thermalzone-number-args-refreshrate)
-    - [`Thermal Zone Args RefreshRate`](#thermal-zone-args-refreshrate)
-    - [`CpuFreq Args RefreshRate`](#cpufreq-args-refreshrate)
-    - [`CoreTemp Args RefreshRate`](#coretemp-args-refreshrate)
-    - [`MultiCoreTemp Args RefreshRate`](#multicoretemp-args-refreshrate)
-    - [`Volume Mixer Element Args RefreshRate`](#volume-mixer-element-args-refreshrate)
-    - [`Alsa Mixer Element Args`](#alsa-mixer-element-args)
-    - [`MPD Args RefreshRate`](#mpd-args-refreshrate)
-    - [`MPDX Args RefreshRate Alias`](#mpdx-args-refreshrate-alias)
-    - [`Mpris1 PlayerName Args RefreshRate`](#mpris1-playername-args-refreshrate)
-    - [`Mpris2 PlayerName Args RefreshRate`](#mpris2-playername-args-refreshrate)
-    - [`Mail Args Alias`](#mail-args-alias)
-    - [`MailX Args Opts Alias`](#mailx-args-opts-alias)
-    - [`MBox Mboxes Opts Alias`](#mbox-mboxes-opts-alias)
-    - [`NotmuchMail Alias Args Rate`](#notmuchmail-alias-args-rate)
-    - [`XPropertyLog PropName`](#xpropertylog-propname)
-    - [`UnsafeXPropertyLog PropName`](#unsafexpropertylog-propname)
-    - [`NamedXPropertyLog PropName Alias`](#namedxpropertylog-propname-alias)
-    - [`UnsafeNamedXPropertyLog PropName Alias`](#unsafenamedxpropertylog-propname-alias)
-    - [`Brightness Args RefreshRate`](#brightness-args-refreshrate)
-    - [`Kbd Opts`](#kbd-opts)
-    - [`Locks`](#locks)
-    - [`CatInt n filename`](#catint-n-filename)
-    - [`UVMeter`](#uvmeter)
-- [Executing External Commands](#executing-external-commands)
-- [Other Plugins](#other-plugins)
-    - [`StdinReader`](#stdinreader)
-    - [`UnsafeStdinReader`](#unsafestdinreader)
-    - [`Date Format Alias RefreshRate`](#date-format-alias-refreshrate)
-    - [`DateZone Format Locale Zone Alias RefreshRate`](#datezone-format-locale-zone-alias-refreshrate)
-    - [`CommandReader "/path/to/program" Alias`](#commandreader-pathtoprogram-alias)
-    - [`PipeReader "default text:/path/to/pipe" Alias`](#pipereader-default-textpathtopipe-alias)
-    - [`MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias`](#marqueepipereader-default-textpathtopipe-length-rate-sep-alias)
-    - [`BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]`](#bufferedpipereader-alias-timeout-bool-pathtopipe1-)
-    - [`XMonadLog`](#xmonadlog)
-    - [`UnsafeXMonadLog`](#unsafexmonadlog)
-    - [`HandleReader Handle Alias`](#handlereader-handle-alias)
-- [The DBus Interface](#the-dbus-interface)
-    - [Example for using the DBus IPC interface with XMonad](#example-for-using-the-dbus-ipc-interface-with-xmonad)
-- [User plugins](#user-plugins)
-    - [Writing a Plugin](#writing-a-plugin)
-    - [Using a Plugin](#using-a-plugin)
-    - [Configurations written in pure Haskell](#configurations-written-in-pure-haskell)
-- [Authors and credits](#authors-and-credits)
-    - [Thanks](#thanks)
-- [Related](#related)
-- [License](#license)
-
-<!-- markdown-toc end -->
-
-# About
-
-Xmobar is a minimalistic status bar. It was originally designed and
-implemented by Andrea Rossato to work with
-[xmonad](http://xmonad.org), but it is actually usable with any window
-manager.
-
-Xmobar was inspired by the [Ion3](http://tuomov.iki.fi/software/)
-status bar, and supports similar features, like dynamic color
-management, icons, output templates, and extensibility through
-plugins.
-
-These are some xmobar [screenshots](doc/screenshots) using the
-author's configuration:
-
-![](doc/screenshots/xmobar-top.png)
-
-![](doc/screenshots/xmobar-bottom.png)
-
-![](doc/screenshots/xmobar-exwm.png)
-
-This is the [changelog](https://xmobar.org/changelog.html) for recent releases.
-
-# Installation
-
-## Using cabal-install
-
-Xmobar is available from [Hackage], and you can install it using
-`cabal-install`:
-
-        cabal install xmobar
-
-Xmobar versions >= 0.27 require GHC version >= 8.0.2.  Due to an
-intermittent bug in GHC, we recommend using either GHC 8.0.2, 8.2.2 or
-8.6.
-
-See below for a list of optional compilation flags that will enable
-some optional plugins. For instance, to install xmobar with all the
-bells and whistles, use:
-
-        cabal install xmobar --flags="all_extensions"
-
-## From source
-
-If you don't have `cabal-install` installed, you can get xmobar's
-source code in a variety of ways:
-
-  - From [Hackage]. Just download the latest release from xmobar's
-    hackage page.
-  - From [Github]. You can also obtain a tarball in [Github's
-    downloads page]. You'll find there links to each tagged release.
-  - From the bleeding edge repo. If you prefer to live dangerously,
-    just get the latest and greatest (and buggiest, I guess) using
-    git:
-
-        git clone git://github.com/jaor/xmobar
-
-
-[Github's downloads page]: https://github.com/jaor/xmobar/downloads
-
-If you have cabal installed, you can now use it from within xmobar's
-source tree:
-
-        cabal install -fall_extensions
-
-
-There is also a barebones `stack.yaml` file that will allow you to
-build the xmobar executable with stances of the form:
-
-        stack install --flag xmobar:all_extensions
-
-
-## Optional features
-
-You can configure xmobar to include some optional plugins and
-features, which are not compiled by default. To that end, you need to
-add one or more flags to either the cabal install command or the
-configure setup step, as shown in the examples above.
-
-Extensions need additional libraries (listed below) that will be
-automatically downloaded and installed if you're using cabal install.
-Otherwise, you'll need to install them yourself.
-
-- `with_dbus` Enables support for DBUS by making xmobar to publish a
-  service on the session bus.  Requires the [dbus] package.
-
-- `with_threaded` Uses GHC's threaded runtime.  Use this option if
-  xmobar enters a high-CPU regime right after starting.
-
-- `with_utf8` UTF-8 support. Requires the [utf8-string] package.
-
-- `with_xft` Antialiased fonts. Requires the [X11-xft] package. This
-  option automatically enables UTF-8.  To use XFT fonts you need to
-  use the `xft:` prefix in the `font` configuration option. For
-  instance:
-
-    ``` haskell
-        font = "xft:Times New Roman-10:italic"
-    ```
-
-  Or to have fallback fonts, just separate them by commas:
-
-    ``` haskell
-        font = "xft:Open Sans:size=9,WenQuanYi Zen Hei:size=9"
-    ```
-
-- `with_mpd` Enables support for the [MPD] daemon. Requires the
-  [libmpd] package.
-
-- `with_mpris` Enables support for MPRIS v1/v2 protocol.  Requires the
-  [dbus] and [text] packages.
-
-- `with_inotify` Support for inotify in modern Linux kernels. This
-  option is needed for the MBox and Mail plugins to work. Requires the
-  [hinotify] package.
-
-- `with_nl80211` Support for wireless cards on Linux via nl80211 (all
-   upstream drivers). Enables the Wireless plugin. Requires [netlink]
-   and [cereal] packages.
-
-- `with_iwlib` Support for wireless cards via Wext ioctls
-   (deprecated). Enables the Wireless plugin. No Haskell library is
-   required, but you will need the [iwlib] C library and headers in your
-   system (e.g., install `libiw-dev` in Debian-based systems or
-   `wireless_tools` on Arch Linux). Conflicts with `with_nl80211`.
-
-- `with_alsa` Support for ALSA sound cards. Enables the Volume
-   plugin. Requires the [alsa-mixer] package.  To install the latter,
-   you'll need the [libasound] C library and headers in your system
-   (e.g., install `libasound2-dev` in Debian-based systems).
-
-- `with_datezone` Support for other timezones. Enables the DateZone
-   plugin.  Requires [timezone-olson] and [timezone-series] package.
-
-- `with_xpm` Support for xpm image file format. This will allow loading
-  .xpm files in `<icon>`.  Requires the [libXpm] C library.
-
-- `with_uvmeter` Enables UVMeter plugin. The plugin shows UV data for
-   Australia.
-
-- `with_weather` Support to display weather information. Enables
-   Weather plugin.
-
-- `all_extensions` Enables all the extensions above.
-
-# Running xmobar
-
-You can now run xmobar with:
-
-        xmobar /path/to/config &
-
-or
-
-        xmobar &
-
-if you have the default configuration file saved as
-`$XDG\_CONFIG\_HOME/xmobar/xmobarrc` (defaulting to
-`~/.config/xmobar/xmobarrc`), or `~/.xmobarrc`.
-
-## Signal Handling
-
-Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:
-
-- After receiving SIGUSR1 xmobar moves its position to the next screen.
-
-- After receiving SIGUSR2 xmobar repositions itself on the current screen.
-
-# Configuration
-
-## Quick Start
-
-See [examples/xmobar.config] for an example.
-
-[examples/xmobar.config]: http://github.com/jaor/xmobar/raw/master/examples/xmobar.config
-
-For the output template:
-
-- `%command%` will execute command and print the output. The output
-  may contain markups to change the characters' color.
-
-- `<fc=#FF0000>string</fc>` will print `string` with `#FF0000` color
-  (red). `<fc=#FF0000,#000000>string</fc>` will print `string` in red with
-  a black background (`#000000`). Background absolute offsets can be specified
-  for XFT fonts. `<fc=#FF0000,#000000:0>string</fc>` will have a background
-  matching the bar's height.
-
-- `<box>string</box>` will print string surrounded by a box in the
-  foreground color.  The `box` tag accepts several optional arguments
-  to tailor its looks:
-  - `type`: `Top`, `Bottom`, `VBoth` (a single line above or below
-    string, or both), `Left`, `Right`, `HBoth` (single vertical
-    lines), `Full` (a rectangle, the default).
-  - `color`: the color of the box lines.
-  - `width`: the width of the box lines.
-  - `offset`: an alignment char (L, C or R) followed by the amount of
-    pixels to offset the box lines; the alignment denotes the position
-    of the resulting line, with L/R meaning top/bottom for the
-    vertical lines, and left/right for horizontal ones.
-  - `mt`, `mb`, `ml`, `mr` specify margins to be added at the top,
-    bottom, left and right lines.
-
-  For example, a box underlining its text with a red line of width 2:
-
-           <box type=Bottom width=2 color=red>string</box>
-
-  and if you wanted an underline and an overline with a margin of 2
-  pixels either side:
-
-           <box type=VBoth mt=2 mb=2>string</box>
-
-- `<fn=1>string</fn>` will print `string` with the first font from
-  `additionalFonts`.  The index `0` corresponds to the standard font.
-
-- `<icon=/path/to/icon.xbm/>` will insert the given bitmap. XPM image
-  format is also supported when compiled with `--flags="with_xpm"`.
-
-- ```<action=`command` button=12345>``` will execute given command
-  when clicked with specified buttons. If not specified, button is
-  equal to 1 (left mouse button). Using old syntax (without backticks
-  surrounding `command`) will result in `button` attribute being
-  ignored.
-
-- `<raw=len:str/>` allows the encapsulation of arbitrary text `str` (which
-  must be `len` `Char`s long, where `len` is encoded as a decimal sequence).
-  Careful use of this and `UnsafeStdinReader`, for example, permits window
-  managers to feed xmobar strings with `<action>` tags mixed with un-trusted
-  content (e.g. window titles).  For example, if xmobar is invoked as
-
-        xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"
-
-  and receives on standard input the line
-
-        <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`
-
-  then it will display the text ```<action=`echo mooo` button=1>foo</action>```,
-  which, when clicked, will cause `test` to be echoed.
-
-Other configuration options:
-
-- `font` Name of the font to be used. Use the `xft:` prefix for XFT
-  fonts.
-
-- `additionalFonts` Haskell-style list of fonts to be used with the
-  `fn`-template.  Use the `xft:` prefix for XFT fonts.  See also
-  `textOffsets` below.
-
-- `bgColor` Background color.
-
-- `fgColor` Default font color.
-
-- `alpha` The transparency.  0 is transparent, 255 is opaque.
-
-- `position` Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW,
-  BottomSize or Static (with x, y, width and height).
-
-  TopP and BottomP take 2 arguments: left padding and right padding.
-
-  TopW and BottomW take 2 arguments: an alignment parameter (L for
-  left, C for centered, R for Right) and an integer for the percentage
-  width xmobar window will have in respect to the screen width.
-
-  TopSize and BottomSize take 3 arguments: an alignment parameter, an
-  integer for the percentage width, and an integer for the minimum
-  pixel height that the xmobar window will have.
-
-  For example:
-
-    ``` haskell
-        position = BottomW C 75
-    ```
-
-  to place xmobar at the bottom, centered with the 75% of the screen
-  width.  Or
-
-    ``` haskell
-        position = BottomP 120 0
-    ```
-
-  to place xmobar at the bottom, with 120 pixel indent of the left.
-  Or
-
-    ``` haskell
-        position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }
-    ```
-
-  or
-
-    ``` haskell
-        position = Top
-    ```
-
-- `textOffset` The vertical offset, in pixels, for the text baseline.
-   If negative or not given, xmobar will try to center text
-   vertically.
-
-- `textOffsets` A list of vertical offsets, in pixels, for the text
-   baseline, to be used with the each of the fonts in
-   `additionalFonts` (if any).  If negative or not given, xmobar will
-   try to center text vertically for that font.
-
-- `iconOffset` The vertical offset, in pixels, for icons bottom line.
-   If negative or not given, xmobar will try to center icons
-   vertically.
-
-- `lowerOnStart` When True the window is sent the bottom of the window
-  stack initially.
-
-- `hideOnStart` When set to True the window is initially not mapped,
-  i.e. hidden. It then can be toggled manually (for example using the
-  dbus interface) or automatically (by a plugin) to make it reappear.
-
-- `allDesktops` When set to True (the default), xmobar will tell the
-  window manager explicitly to be shown in all desktops, by setting
-  `_NET_WM_DESKTOP` to 0xffffffff.
-
-- `overrideRedirect` If you're running xmobar in a tiling window
-  manager, you might need to set this option to `False` so that it
-  behaves as a docked application.  Defaults to `True`.
-
-- `pickBroadest` When multiple displays are available, xmobar will
-  choose by default the first one to place itself.  With this flag set
-  to `True` (the default is `False`) it will choose the broadest one
-  instead.
-
-- `persistent` When True the window status is fixed i.e. hiding or
-  revealing is not possible. This option can be toggled at
-  runtime. Defaults to False.
-
-- `border` TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder
-  (default).
-
-  TopB, BottomB, FullB take no arguments, and request drawing a border
-  at the top, bottom or around xmobar's window, respectively.
-
-  TopBM, BottomBM, FullBM take an integer argument, which is the
-  margin, in pixels, between the border of the window and the drawn
-  border.
-
-- `borderColor` Border color.
-
-- `borderWidth` Border width in pixels.
-
-- `iconRoot` Root folder where icons are stored. For <icon=path/> if
-  path start with `"/"`, `"./"` or `"../"` it is interpreted as it is.
-  Otherwise it will have `iconRoot ++ "/"` prepended to it. Default is
-  `"."`.
-
-- `commands` For setting the options of the programs to run
-  (optional).
-
-- `sepChar` The character to be used for indicating commands in the
-  output template (default '%').
-
-- `alignSep` a 2 character string for aligning text in the output
-  template. The text before the first character will be align to left,
-  the text in between the 2 characters will be centered, and the text
-  after the second character will be align to the right.
-
-- `template` The output template.
-
-- `wmClass` The value for the window's X11 WM_CLASS property.
-  Defaults to "xmobar".
-
-- `wmName` The value for the window's X11 WM_NAME property.  Defaults
-  to "xmobar".
-
-### Running xmobar with i3status
-
-xmobar can be used to display information generated by [i3status], a
-small program that gathers system information and outputs it in
-formats suitable for being displayed by the dzen2 status bar, wmii's
-status bar or xmobar's `StdinReader`.  See [i3status manual] for
-further details.
-
-### Dynamically sizing xmobar
-
-See [this idea] by Jonas Camillus Jeppensen for a way of adapting
-dynamically xmobar's size and run it alongside a system tray widget
-such as trayer or stalonetray (although the idea is not limited to
-trays, really).  For your convenience, there is a version of Jonas'
-script in [examples/padding-icon.sh](./examples/padding-icon.sh).
-
-[this idea]: https://github.com/jaor/xmobar/issues/239#issuecomment-233206552
-
-## Command Line Options
-
-xmobar can be either configured with a configuration file or with
-command line options. In the second case, the command line options
-will overwrite the corresponding options set in the configuration
-file.
-
-Example:
-
-        xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'
-
-This is the list of command line options (the output of
-xmobar --help):
-
-        Usage: xmobar [OPTION...] [FILE]
-        Options:
-          -h, -?        --help                 This help
-          -V            --version              Show version information
-          -v            --verbose              Emit verbose debugging messages
-          -r            --recompile            Force recompilation (for Haskell FILE)
-          -f font name  --font=font name       Font name
-          -N font name  --add-font=font name   Add to the list of additional fonts
-          -w class      --wmclass=class        X11 WM_CLASS property
-          -n name       --wmname=name          X11 WM_NAME property
-          -B bg color   --bgcolor=bg color     Background color. Default black
-          -F fg color   --fgcolor=fg color     Foreground color. Default grey
-          -A alpha      --alpha=alpha          Transparency: 0 is transparent
-                                               and 255 (the default) is opaque
-          -o            --top                  Place xmobar at the top of the screen
-          -b            --bottom               Place xmobar at the bottom of the screen
-          -p            --position=position    Specify position, same as in config file
-          -d            --dock                 Try to start xmobar as a dock
-          -a alignsep   --alignsep=alignsep    Separators for left, center and right text
-                                               alignment. Default: '}{'
-          -s char       --sepchar=char         Character used to separate commands in
-                                               the output template. Default '%'
-          -t template   --template=template    Output template
-          -i path       --iconroot=path        Default directory for icon pattern files
-          -c commands   --commands=commands    List of commands to be executed
-          -C command    --add-command=command  Add to the list of commands to be executed
-          -x screen     --screen=screen        On which X screen number to start
-
-        Mail bug reports and suggestions to <mail@jao.io>
-
-
-## The Output Template
-
-The output template must contain at least one command. xmobar will
-parse the template and will search for the command to be executed in
-the `commands` configuration option. First an `alias` will be searched
-(plugins such as Weather or Network have default aliases, see below).
-After that, the command name will be tried. If a command is found, the
-arguments specified in the `commands` list will be used.
-
-If no command is found in the `commands` list, xmobar will ask the
-operating system to execute a program with the name found in the
-template. If the execution is not successful an error will be
-reported.
-
-It's possible to insert in the global templates icon directives of the
-form:
-
-        <icon=/path/to/bitmap.xbm/>
-
-which will produce the expected result. Accepted image formats are XBM
-and XPM (when `with_xpm` flag is enabled). If path does not start with
-`"/"`, `"./"`, `"../"` it will have `iconRoot ++ "/"` prepended to it.
-
-It's also possible to use action directives of the form:
-
-        <action=`command` button=12345>
-
-which will be executed when clicked on with specified mouse buttons. This tag
-can be nested, allowing different commands to be run depending on button clicked.
-
-## The `commands` Configuration Option
-
-The `commands` configuration option is a list of commands information
-and arguments to be used by xmobar when parsing the output template.
-Each member of the list consists in a command prefixed by the `Run`
-keyword. Each command has arguments to control the way xmobar is going
-to execute it.
-
-The option consists in a list of commands separated by a comma and
-enclosed by square parenthesis.
-
-Example:
-
-  ``` haskell
-      [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]
-  ```
-
-to run the Memory monitor plugin with the specified template, and the
-swap monitor plugin, with default options, every second.  And here's
-an example of a template for the commands above using an icon:
-
-  ``` haskell
-      template="<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"
-  ```
-
-This example will run "xclock" command when date is clicked:
-
-  ``` haskell
-      template="<action=`xclock`>%date%</action>
-  ```
-
-The only internal available command is `Com` (see below Executing
-External Commands). All other commands are provided by plugins. xmobar
-comes with some plugins, providing a set of system monitors, a
-standard input reader, an Unix named pipe reader, a configurable date
-plugin, and 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,
-
-  ``` haskell
-      Run Brightness
-        [ "-t", "<ipat>"
-        , "--"
-        , "--brightness-icon-pattern", "<icon=bright_%%.xpm/>"
-        ] 30
-  ```
-
-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.:
-
-  ``` haskell
-      Run Weather "EGPF" ["-t", "<station>: <tempC>C"] 36000
-  ```
-
-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:
-
-        Glasgow Airport: 16.0C
-
-
-## `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.
-
-## `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:
-
-  ``` 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
-  ```
-
-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 `--flags="with_nl80211"` or
-  `--flags="with_iwlib"` 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
-
-    ``` haskell
-        BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate
-    ```
-
-## `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):
-
-    ``` 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
-    ```
-
-  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:
-
-    ``` haskell
-        Run BatteryP ["BAT0"]
-                     ["-t", "<acstatus>"
-                     , "-L", "10", "-H", "80"
-                     , "-l", "red", "-h", "green"
-                     , "--", "-O", "Charging", "-o", "Battery: <left>%"
-                     ] 10
-    ```
-
-- 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:
-
-    ``` haskell
-        DiskU [("/", "<used>/<size>"), ("sdb1", "<usedbar>")]
-              ["-L", "20", "-H", "50", "-m", "1", "-p", "3"]
-              20
-    ```
-
-## `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:
-
-    ``` haskell
-        DiskIO [("/", "<read> <write>"), ("sdb1", "<total>")] [] 10
-    ```
-
-## `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:
-
-    ``` haskell
-        Run ThermalZone 0 ["-t","<id>: <temp>C"] 30
-    ```
-
-## `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:
-
-    ``` haskell
-        Run Thermal "THRM" ["-t","iwl4965-temp: <temp>C"] 50
-    ```
-
-## `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:
-
-    ``` haskell
-        Run CpuFreq ["-t", "Freq:<cpu0>|<cpu1>GHz", "-L", "0", "-H", "2",
-                     "-l", "lightblue", "-n","white", "-h", "red"] 50
-    ```
-
-## `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:
-
-    ``` haskell
-        Run CoreTemp ["-t", "Temp:<core0>|<core1>C",
-                      "-L", "40", "-H", "60",
-                      "-l", "lightblue", "-n", "gray90", "-h", "red"] 50
-    ```
-
-## `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:
-
-    ``` haskell
-        Run MultiCoreTemp ["-t", "Temp: <avg>°C | <avgpc>%",
-                           "-L", "60", "-H", "80",
-                           "-l", "green", "-n", "yellow", "-h", "red",
-                           "--", "--mintemp", "20", "--maxtemp", "100"] 50
-    ```
-
-## `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 [alsa-core] and [alsa-mixer] installed in your
-  system. In addition, to activate this plugin you must pass
-  `--flags="with_alsa"` during compilation.
-
-## `Alsa Mixer Element Args`
-
-Like [Volume](#volume-mixer-element-args-refreshrate), 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 [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):
-
-    ``` haskell
-        Run MPD ["-t",
-                 "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]",
-                 "--", "-P", ">>", "-Z", "|", "-S", "><"] 10
-    ```
-
-## `MPDX Args RefreshRate Alias`
-
-Like `MPD` but uses as alias its last argument instead of "mpd".
-
-## `Mpris1 PlayerName Args RefreshRate`
-
-- Aliases to `mpris1`
-- Requires [dbus] and [text] packages.
-  To activate, pass `--flags="with_mpris"` 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:
-
-    ``` haskell
-        Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10
-    ```
-
-## `Mpris2 PlayerName Args RefreshRate`
-
-- Aliases to `mpris2`
-- Requires [dbus] and [text] packages.
-  To activate, pass `--flags="with_mpris"` 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:
-
-    ``` haskell
-        Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10
-    ```
-
-## `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
-  [hinotify] package. To activate, pass `--flags="with_inotify"`
-  during compilation.
-- Example:
-
-    ``` haskell
-        Run Mail [("inbox", "~/var/mail/inbox"),
-                  ("lists", "~/var/mail/lists")]
-                 "mail"
-    ```
-
-## `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
-  [hinotify] package. To activate, pass `--flags="with_inotify"`
-  during compilation.
-- Example:
-
-    ``` haskell
-        Run MailX [("I", "inbox", "green"),
-                   ("L", "lists", "orange")]
-                  ["-d", "~/var/mail", "-p", " ", "-s", " "]
-                  "mail"
-    ```
-
-## `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
-  [hinotify] package. To activate, pass `--flags="with_inotify"`
-  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`:
-
-    ``` haskell
-        Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")]
-                 ["-d", "/var/mail/", "-p", " "] "mbox"
-    ```
-
-## `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
-
-    ``` haskell
-        [ MailItem "name" "address" "query"
-        ...
-        ]
-    ```
-
-  or, using explicit record syntax:
-
-    ``` haskell
-        [ MailItem
-            { name    = "name"
-            , address = "address"
-            , query   = "query"
-            }
-          ...
-        ]
-    ```
-
-  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:
-
-      ``` haskell
-          MailItem "mbs:" "soliditsallgood@mailbox.org" ""
-      ```
-
-  - A single `MailItem` that displays all unread threads with
-    "[My-Subject]" somewhere in the title:
-
-      ``` haskell
-        MailItem "S:" "" "subject:[My-Subject]"
-      ```
-
-  - A full example of a `NotmuchMail` configuration:
-
-      ``` 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
-      ```
-
-## `XPropertyLog PropName`
-
-- Aliases to `PropName`
-- Reads the X property named by `PropName` (a string) and displays its
-  value. The [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.
-
-[examples/xmonadpropwrite.hs script]: https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs
-
-## `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:
-
-    ``` haskell
-        Run Brightness ["-t", "<bar>"] 60
-    ```
-
-## `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:
-
-    ``` haskell
-        Run Kbd [("us(dvorak)", "DV"), ("us", "US")]
-    ```
-
-## `Locks`
-
-- Displays the status of Caps Lock, Num Lock and Scroll Lock.
-- Aliases to `locks`
-- Example:
-
-    ``` haskell
-        Run Locks
-    ```
-
-## `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:
-
-    ``` haskell
-        Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50
-    ```
-
-## `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:
-
-    ``` haskell
-        Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
-    ```
-
-# 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.:
-
-  ``` haskell
-      Run Com "uname" ["-s","-r"] "" 0
-  ```
-
-can be used in the output template as `%uname%` (and xmobar will call
-_uname_ only once), while
-
-  ``` haskell
-      Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600
-  ```
-
-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:
-
-  ``` haskell
-      Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600
-  ```
-
-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:
-  ```<action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>```
-
-## `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:
-
-  ``` haskell
-      Run Date "%a %b %_d %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10
-  ```
-
-## `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:
-
-    ``` haskell
-        Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10
-    ```
-
-## `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
-
-    ``` haskell
-        Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"
-    ```
-
-- 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:
-
-    ``` haskell
-        Run BufferedPipeReader "bpr"
-            [ (  0, False, "/tmp/xmobar_window"  )
-            , ( 15,  True, "/tmp/xmobar_status"  )
-            ]
-    ```
-
-  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 [examples/status.sh]
-- Expands environment variables for the pipe path
-
-[examples/status.sh]: http://github.com/jaor/xmobar/raw/master/examples/status.sh
-
-
-## `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 [here]):
-
-    ``` haskell
-        main = do
-          spawn "xmobar"
-          xmonad $ defaultConfig {
-            logHook = dynamicLogString defaultPP >>= xmonadPropLog
-          }
-    ```
-
-   This plugin can be used as a sometimes more convenient alternative
-   to `StdinReader`. For instance, it allows you to (re)start xmobar
-   outside xmonad.
-
-[here]: http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Hooks-DynamicLog.html
-
-## `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:
-
-    ``` haskell
-        myPP = defaultPP { ppTitle = xmobarStrip }
-        main = xmonad $ defaultConfig {
-          logHook = dynamicLogString myPP >>= xmonadPropLog
-        }
-    ```
-
-## `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:
-
-    ``` haskell
-        (readHandle, writeHandle) <- createPipe
-        xmobarProcess <- forkProcess $ xmobar myConfig
-                { commands =
-                    Run (HandleReader readHandle "handle") : commands myConfig
-                }
-        hPutStr writeHandle "Hello World"
-    ```
-
-# The DBus Interface
-
-When compiled with the optional `with_dbus` flag, xmobar can be
-controlled over dbus. All signals defined in [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.
-
-[src/Signal.hs]: https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs
-
-- 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:
-
-        dbus-send \
-            --session \
-            --dest=org.Xmobar.Control \
-            --type=method_call \
-            --print-reply \
-            '/org/Xmobar/Control' \
-            org.Xmobar.Control.SendSignal \
-            "string:Toggle 0"
-
-It is also possible to send multiple signals at once:
-
-        # send to another screen, reveal and toggle the persistent flag
-        dbus-send [..] \
-            "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent"
-
-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.
-
-  ``` haskell
-      ((0, xK_Alt_L   ), return ())
-  ```
-
-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).
-
-  ``` 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
-  ```
-
-# 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 2
-optional ones (alias and rate):
-
-  ``` haskell
-      start :: e -> (String -> IO ()) -> IO ()
-      run   :: e -> IO String
-      rate  :: e -> Int
-      alias :: e -> String
-  ```
-
-`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 `examples/xmobar.hs` for an
-example of a plugin that runs just once, and
-`src/Xmobar/Plugins/Date.hs` for one that implements `rate`.
-
-Notice that Date could be implemented as:
-
-  ``` 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
-  ```
-
-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 [the author's
-configuration](https://gitlab.com/jaor/xmobar-config/).
-
-# Authors and credits
-
-Andrea Rossato originally designed and implemented xmobar up to
-version 0.11.1. Since then, it is maintained and developed by
-[jao](https://jao.io), with the help of the greater xmobar and Haskell
-communities.
-
-In particular, xmobar incorporates patches by Mohammed Alshiekh, Alex
-Ameen, Axel Angel, Dhananjay Balan, Claudio Bley, Dragos Boca, Ben
-Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick Chilton,
-Antoine Eiche, Nathaniel Wesley Filardo, John Goerzen, Reto Hablützel,
-Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost,
-Jochen Keil, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry
-Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry
-Malikov, David McLean, Marcin Mikołajczyk, Dino Morelli, Tony Morris,
-Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner,
-Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr
-Rockai, Andrew Emmanuel Rosa, Sackville-West, Markus Scherer, Daniel
-Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov,
-Peter Simons, Alexander Solovyov, Will Song, John Soros, Felix
-Springer, Travis Staton, Artem Tarasov, Samuli Thomasson, Edward
-Tjörnhammar, Sergei Trofimovich, Thomas Tuegel, John Tyree, Jan
-Vornberger, Anton Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun
-Hu, Edward Z. Yang and Norbert Zeh.
-
-## Thanks
-
-__Andrea Rossato__:
-
-Thanks to Robert Manea and Spencer Janssen for their help in
-understanding how X works. They gave me suggestions on how to solve
-many problems with xmobar.
-
-Thanks to Claus Reinke for make me understand existential types (or at
-least for letting me think I grasp existential types...;-).
-
-__jao__:
-
-Thanks to Andrea for creating xmobar in the first place, and for
-giving me the chance to contribute.
-
-# Related
-
-- To understand the internal mysteries of xmobar you may try reading
-  [this tutorial] on X Window Programming in Haskell.
-
-[this tutorial]: http://www.haskell.org/haskellwiki/X_window_programming_in_Haskell
-
-# License
-
-This software is released under a BSD-style license. See [license] for
-more details.
-
-Copyright &copy; 2010-2020 Jose Antonio Ortega Ruiz
-
-Copyright &copy; 2007-2010 Andrea Rossato
-
-[Github]: http://github.com/jaor/xmobar/
-[Github page]: http://github.com/jaor/xmobar
-[Hackage]: http://hackage.haskell.org/package/xmobar/
-[LICENSE]: https://github.com/jaor/xmobar/raw/master/license
-[Mailing list]: http://projects.haskell.org/cgi-bin/mailman/listinfo/xmobar
-[MPD]: http://mpd.wikia.com/
-[X11-xft]: http://hackage.haskell.org/package/X11-xft/
-[i3status]: http://i3wm.org/i3status/
-[i3status manual]: http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar
-[iwlib]: http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html
-[libasound]: http://packages.debian.org/stable/libasound2-dev
-[hinotify]: http://hackage.haskell.org/package/hinotify/
-[libmpd]: http://hackage.haskell.org/package/libmpd/
-[dbus]: http://hackage.haskell.org/package/dbus
-[text]: http://hackage.haskell.org/package/text
-[sawfish]: http://sawfish.wikia.com/
-[utf8-string]: http://hackage.haskell.org/package/utf8-string/
-[alsa-core]: http://hackage.haskell.org/package/alsa-core
-[alsa-mixer]: http://hackage.haskell.org/package/alsa-mixer
-[timezone-olson]: http://hackage.haskell.org/package/timezone-olson
-[timezone-series]: http://hackage.haskell.org/package/timezone-series
-[libXpm]: http://cgit.freedesktop.org/xorg/lib/libXpm
-[http-conduit]: http://hackage.haskell.org/package/http-conduit
-[http-types]: http://hackage.haskell.org/package/http-types
diff --git a/readme.org b/readme.org
new file mode 100644
index 0000000..cab1e29
--- /dev/null
+++ b/readme.org
@@ -0,0 +1,2183 @@
+[[http://hackage.haskell.org/package/xmobar][https://img.shields.io/hackage/v/xmobar.svg]]
+
+* About
+
+Xmobar is a minimalistic status bar. It was originally designed and
+implemented by Andrea Rossato to work with [[http://xmonad.org][xmonad]], but it is actually
+usable with any window manager.
+
+Xmobar was inspired by the [[http://tuomov.iki.fi/software/][Ion3]] status bar, and supports similar
+features, like dynamic color management, icons, output templates, and
+extensibility through plugins.
+
+These are some xmobar [[file:doc/screenshots][screenshots]] using the author's configuration:
+
+[[file:doc/screenshots/xmobar-top.png]]
+
+[[file:doc/screenshots/xmobar-bottom.png]]
+
+[[file:doc/screenshots/xmobar-exwm.png]]
+
+This is the [[https://xmobar.org/changelog.html][changelog]] for recent releases.
+
+* Installation
+** Using cabal-install
+
+Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using
+=cabal-install=:
+
+#+begin_src shell
+  cabal install xmobar
+#+end_src
+
+Xmobar versions >= 0.27 require GHC version >= 8.0.2. Due to an
+intermittent bug in GHC, we recommend using either GHC 8.0.2, 8.2.2 or
+8.6.
+
+See below for a list of optional compilation flags that will enable some
+optional plugins. For instance, to install xmobar with all the bells and
+whistles, use:
+
+#+begin_src shell
+  cabal install xmobar --flags="all_extensions"
+#+end_src
+
+** From source
+
+If you don't have =cabal-install= installed, you can get xmobar's source
+code in a variety of ways:
+
+- From [[http://hackage.haskell.org/package/xmobar/][Hackage]]. Just download the latest release from xmobar's hackage
+  page.
+
+- From [[http://github.com/jaor/xmobar/][Github]]. You can also obtain a tarball in [[https://github.com/jaor/xmobar/downloads][Github's downloads
+  page]]. You'll find there links to each tagged release.
+
+- From the bleeding edge repo. If you prefer to live dangerously, just
+  get the latest and greatest (and buggiest, I guess) using git:
+
+  #+begin_src shell
+    git clone git://github.com/jaor/xmobar
+  #+end_src
+
+If you have cabal installed, you can now use it from within xmobar's
+source tree:
+
+#+begin_src shell
+  cabal install -fall_extensions
+#+end_src
+
+There is also a barebones =stack.yaml= file that will allow you to build
+the xmobar executable with stances of the form:
+
+#+begin_src shell
+  stack install --flag xmobar:all_extensions
+#+end_src
+
+** Optional features
+
+You can configure xmobar to include some optional plugins and features,
+which are not compiled by default. To that end, you need to add one or
+more flags to either the cabal install command or the configure setup
+step, as shown in the examples above.
+
+Extensions need additional libraries (listed below) that will be
+automatically downloaded and installed if you're using cabal install.
+Otherwise, you'll need to install them yourself.
+
+- =with_dbus= Enables support for DBUS by making xmobar to publish a
+  service on the session bus. Requires the [[http://hackage.haskell.org/package/dbus][dbus]] package.
+
+- =with_threaded= Uses GHC's threaded runtime. Use this option if xmobar
+  enters a high-CPU regime right after starting.
+
+- =with_utf8= UTF-8 support. Requires the [[http://hackage.haskell.org/package/utf8-string/][utf8-string]] package.
+
+- =with_xft= Antialiased fonts. Requires the [[http://hackage.haskell.org/package/X11-xft/][X11-xft]] package. This
+  option automatically enables UTF-8. To use XFT fonts you need to use
+  the =xft:= prefix in the =font= configuration option. For instance:
+
+  #+begin_src haskell
+    font = "xft:Times New Roman-10:italic"
+  #+end_src
+
+  Or to have fallback fonts, just separate them by commas:
+
+  #+begin_src haskell
+    font = "xft:Open Sans:size=9,WenQuanYi Zen Hei:size=9"
+  #+end_src
+
+- =with_mpd= Enables support for the [[http://mpd.wikia.com/][MPD]] daemon. Requires the [[http://hackage.haskell.org/package/libmpd/][libmpd]]
+  package.
+
+- =with_mpris= Enables support for MPRIS v1/v2 protocol. Requires the
+  [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages.
+
+- =with_inotify= Support for inotify in modern Linux kernels. This
+  option is needed for the MBox and Mail plugins to work. Requires the
+  [[http://hackage.haskell.org/package/hinotify/][hinotify]] package.
+
+- =with_nl80211= Support for wireless cards on Linux via nl80211 (all
+  upstream drivers). Enables the Wireless plugin. Requires [netlink] and
+  [cereal] packages.
+
+- =with_iwlib= Support for wireless cards via Wext ioctls (deprecated).
+  Enables the Wireless plugin. No Haskell library is required, but you
+  will need the [[http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html][iwlib]] C library and headers in your system (e.g.,
+  install =libiw-dev= in Debian-based systems or =wireless_tools= on
+  Arch Linux). Conflicts with =with_nl80211=.
+
+- =with_alsa= Support for ALSA sound cards. Enables the Volume plugin.
+  Requires the [[http://hackage.haskell.org/package/alsa-mixer][alsa-mixer]] package.  To install the latter, you'll need
+  the [[http://packages.debian.org/stable/libasound2-dev][libasound]] C library and headers in your system (e.g., install
+  =libasound2-dev= in Debian-based systems).
+
+- =with_datezone= Support for other timezones. Enables the DateZone
+  plugin. Requires [[http://hackage.haskell.org/package/timezone-olson][timezone-olson]] and [[http://hackage.haskell.org/package/timezone-series][timezone-series]] package.
+
+- =with_xpm= Support for xpm image file format. This will allow loading
+  .xpm files in =<icon>=. Requires the [[http://cgit.freedesktop.org/xorg/lib/libXpm][libXpm]] C library.
+
+- =with_uvmeter= Enables UVMeter plugin. The plugin shows UV data for
+  Australia.
+
+- =with_weather= Support to display weather information. Enables Weather
+  plugin.
+
+- =all_extensions= Enables all the extensions above.
+
+* Running xmobar
+
+You can now run xmobar with:
+
+#+begin_src shell
+  xmobar /path/to/config &
+#+end_src
+
+or
+
+#+begin_src shell
+  xmobar &
+#+end_src
+
+if you have the default configuration file saved as
+=$XDG\_CONFIG\_HOME/xmobar/xmobarrc= (defaulting to
+=~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=.
+
+** Signal Handling
+
+Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:
+
+- After receiving SIGUSR1 xmobar moves its position to the next screen.
+
+- After receiving SIGUSR2 xmobar repositions itself on the current
+  screen.
+
+* Configuration
+
+** Quick Start
+
+See [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][examples/xmobar.config]] for an example.
+
+For the output template:
+
+- =%command%= will execute command and print the output. The output may
+  contain markups to change the characters' color.
+
+- =<fc=#FF0000>string</fc>= will print =string= with =#FF0000= color
+  (red). =<fc=#FF0000,#000000>string</fc>= will print =string= in red
+  with a black background (=#000000=). Background absolute offsets can
+  be specified for XFT fonts. =<fc=#FF0000,#000000:0>string</fc>= will
+  have a background matching the bar's height.
+
+- =<box>string</box>= will print string surrounded by a box in the
+  foreground color. The =box= tag accepts several optional arguments to
+  tailor its looks:
+
+  - =type=: =Top=, =Bottom=, =VBoth= (a single line above or below
+    string, or both), =Left=, =Right=, =HBoth= (single vertical lines),
+    =Full= (a rectangle, the default).
+  - =color=: the color of the box lines.
+  - =width=: the width of the box lines.
+  - =offset=: an alignment char (L, C or R) followed by the amount of
+    pixels to offset the box lines; the alignment denotes the position
+    of the resulting line, with L/R meaning top/bottom for the vertical
+    lines, and left/right for horizontal ones.
+  - =mt=, =mb=, =ml=, =mr= specify margins to be added at the top,
+    bottom, left and right lines.
+
+  For example, a box underlining its text with a red line of width 2:
+
+  #+begin_src shell
+    <box type=Bottom width=2 color=red>string</box>
+  #+end_src
+
+  and if you wanted an underline and an overline with a margin of 2
+  pixels either side:
+
+  #+begin_src shell
+    <box type=VBoth mt=2 mb=2>string</box>
+  #+end_src
+
+- =<fn=1>string</fn>= will print =string= with the first font from
+  =additionalFonts=. The index =0= corresponds to the standard font.
+
+- =<icon=/path/to/icon.xbm/>= will insert the given bitmap. XPM image
+  format is also supported when compiled with the =with_xpm= flag.
+
+- =<action=`command` button=12345>= will execute given command when
+  clicked with specified buttons. If not specified, button is equal to 1
+  (left mouse button). Using old syntax (without backticks surrounding
+  =command=) will result in =button= attribute being ignored.
+
+- =<raw=len:str/>= allows the encapsulation of arbitrary text =str=
+  (which must be =len= =Char=s long, where =len= is encoded as a decimal
+  sequence). Careful use of this and =UnsafeStdinReader=, for example,
+  permits window managers to feed xmobar strings with =<action>= tags
+  mixed with un-trusted content (e.g. window titles). For example, if
+  xmobar is invoked as
+
+  #+begin_src shell
+    xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"
+  #+end_src
+
+  and receives on standard input the line
+
+  #+begin_src shell
+    <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`
+  #+end_src
+
+  then it will display the text
+  =<action=`echo mooo` button=1>foo</action>=, which, when clicked, will
+  cause =test= to be echoed.
+
+Other configuration options:
+
+- =font= Name of the font to be used. Use the =xft:= prefix for XFT
+  fonts.
+
+- =additionalFonts= Haskell-style list of fonts to be used with the
+  =fn=-template. Use the =xft:= prefix for XFT fonts. See also
+  =textOffsets= below.
+
+- =bgColor= Background color.
+
+- =fgColor= Default font color.
+
+- =alpha= The transparency. 0 is transparent, 255 is opaque.
+
+- =position= Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW,
+  BottomSize or Static (with x, y, width and height).
+
+  TopP and BottomP take 2 arguments: left padding and right padding.
+
+  TopW and BottomW take 2 arguments: an alignment parameter (L for left,
+  C for centered, R for Right) and an integer for the percentage width
+  xmobar window will have in respect to the screen width.
+
+  TopSize and BottomSize take 3 arguments: an alignment parameter, an
+  integer for the percentage width, and an integer for the minimum pixel
+  height that the xmobar window will have.
+
+  For example:
+
+  #+begin_src haskell
+    position = BottomW C 75
+  #+end_src
+
+  to place xmobar at the bottom, centered with the 75% of the screen
+  width. Or
+
+  #+begin_src haskell
+    position = BottomP 120 0
+  #+end_src
+
+  to place xmobar at the bottom, with 120 pixel indent of the left. Or
+
+  #+begin_src haskell
+    position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }
+  #+end_src
+
+  or
+
+  #+begin_src haskell
+    position = Top
+  #+end_src
+
+- =textOffset= The vertical offset, in pixels, for the text baseline. If
+  negative or not given, xmobar will try to center text vertically.
+
+- =textOffsets= A list of vertical offsets, in pixels, for the text
+  baseline, to be used with the each of the fonts in =additionalFonts=
+  (if any). If negative or not given, xmobar will try to center text
+  vertically for that font.
+
+- =iconOffset= The vertical offset, in pixels, for icons bottom line. If
+  negative or not given, xmobar will try to center icons vertically.
+
+- =lowerOnStart= When True the window is sent the bottom of the window
+  stack initially.
+
+- =hideOnStart= When set to True the window is initially not mapped,
+  i.e. hidden. It then can be toggled manually (for example using the
+  dbus interface) or automatically (by a plugin) to make it reappear.
+
+- =allDesktops= When set to True (the default), xmobar will tell the
+  window manager explicitly to be shown in all desktops, by setting
+  =_NET_WM_DESKTOP= to 0xffffffff.
+
+- =overrideRedirect= If you're running xmobar in a tiling window
+  manager, you might need to set this option to =False= so that it
+  behaves as a docked application. Defaults to =True=.
+
+- =pickBroadest= When multiple displays are available, xmobar will
+  choose by default the first one to place itself. With this flag set to
+  =True= (the default is =False=) it will choose the broadest one
+  instead.
+
+- =persistent= When True the window status is fixed i.e. hiding or
+  revealing is not possible. This option can be toggled at runtime.
+  Defaults to False.
+
+- =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder
+  (default).
+
+  TopB, BottomB, FullB take no arguments, and request drawing a border
+  at the top, bottom or around xmobar's window, respectively.
+
+  TopBM, BottomBM, FullBM take an integer argument, which is the margin,
+  in pixels, between the border of the window and the drawn border.
+
+- =borderColor= Border color.
+
+- =borderWidth= Border width in pixels.
+
+- =iconRoot= Root folder where icons are stored. For =<icon=path/>= if
+  path start with =/=, =./= or =../= it is interpreted as it is.
+  Otherwise it will have
+
+  #+begin_src haskell
+    iconRoot ++ "/"
+  #+end_src
+
+  prepended to it. Default is =.=.
+
+- =commands= For setting the options of the programs to run (optional).
+
+- =sepChar= The character to be used for indicating commands in the
+  output template (default '%').
+
+- =alignSep= a 2 character string for aligning text in the output
+  template. The text before the first character will be align to left,
+  the text in between the 2 characters will be centered, and the text
+  after the second character will be align to the right.
+
+- =template= The output template.
+
+- =wmClass= The value for the window's X11 WM_CLASS property. Defaults
+  to "xmobar".
+
+- =wmName= The value for the window's X11 WM_NAME property. Defaults to
+  "xmobar".
+
+*** Running xmobar with i3status
+
+xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small
+program that gathers system information and outputs it in formats
+suitable for being displayed by the dzen2 status bar, wmii's status bar
+or xmobar's =StdinReader=. See [[http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar][i3status manual]] for further details.
+
+*** Dynamically sizing xmobar
+
+See [[https://github.com/jaor/xmobar/issues/239#issuecomment-233206552][this idea]] by Jonas Camillus Jeppensen for a way of adapting
+dynamically xmobar's size and run it alongside a system tray widget such
+as trayer or stalonetray (although the idea is not limited to trays,
+really). For your convenience, there is a version of Jonas' script in
+[[./examples/padding-icon.sh][examples/padding-icon.sh]].
+
+** Command Line Options
+
+xmobar can be either configured with a configuration file or with
+command line options. In the second case, the command line options will
+overwrite the corresponding options set in the configuration file.
+
+Example:
+
+#+begin_src shell
+  xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'
+#+end_src
+
+This is the list of command line options (the output of xmobar --help):
+
+#+begin_src shell
+  Usage: xmobar [OPTION...] [FILE]
+  Options:
+    -h, -?        --help                 This help
+    -V            --version              Show version information
+    -v            --verbose              Emit verbose debugging messages
+    -r            --recompile            Force recompilation (for Haskell FILE)
+    -f font name  --font=font name       Font name
+    -N font name  --add-font=font name   Add to the list of additional fonts
+    -w class      --wmclass=class        X11 WM_CLASS property
+    -n name       --wmname=name          X11 WM_NAME property
+    -B bg color   --bgcolor=bg color     Background color. Default black
+    -F fg color   --fgcolor=fg color     Foreground color. Default grey
+    -A alpha      --alpha=alpha          Transparency: 0 is transparent
+                                         and 255 (the default) is opaque
+    -o            --top                  Place xmobar at the top of the screen
+    -b            --bottom               Place xmobar at the bottom of the screen
+    -p            --position=position    Specify position, same as in config file
+    -d            --dock                 Try to start xmobar as a dock
+    -a alignsep   --alignsep=alignsep    Separators for left, center and right text
+                                         alignment. Default: '}{'
+    -s char       --sepchar=char         Character used to separate commands in
+                                         the output template. Default '%'
+    -t template   --template=template    Output template
+    -i path       --iconroot=path        Default directory for icon pattern files
+    -c commands   --commands=commands    List of commands to be executed
+    -C command    --add-command=command  Add to the list of commands to be executed
+    -x screen     --screen=screen        On which X screen number to start
+
+  Mail bug reports and suggestions to <mail@jao.io>
+#+end_src
+
+** The Output Template
+
+The output template must contain at least one command. xmobar will parse
+the template and will search for the command to be executed in the
+=commands= configuration option. First an =alias= will be searched
+(plugins such as Weather or Network have default aliases, see below).
+After that, the command name will be tried. If a command is found, the
+arguments specified in the =commands= list will be used.
+
+If no command is found in the =commands= list, xmobar will ask the
+operating system to execute a program with the name found in the
+template. If the execution is not successful an error will be reported.
+
+It's possible to insert in the global templates icon directives of the
+form:
+
+#+begin_src shell
+  <icon=/path/to/bitmap.xbm/>
+#+end_src
+
+which will produce the expected result. Accepted image formats are XBM
+and XPM (when =with_xpm= flag is enabled). If path does not start with
+=/=, =./=, =../= it will have
+
+#+begin_src haskell
+  iconRoot ++ "/"
+#+end_src
+
+prepended to it.
+
+It's also possible to use action directives of the form:
+
+#+begin_src shell
+  <action=`command` button=12345>
+#+end_src
+
+which will be executed when clicked on with specified mouse buttons.
+This tag can be nested, allowing different commands to be run depending
+on button clicked.
+
+** The =commands= Configuration Option
+
+The =commands= configuration option is a list of commands information
+and arguments to be used by xmobar when parsing the output template.
+Each member of the list consists in a command prefixed by the =Run=
+keyword. Each command has arguments to control the way xmobar is going
+to execute it.
+
+The option consists in a list of commands separated by a comma and
+enclosed by square parenthesis.
+
+Example:
+
+#+begin_src haskell
+  [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]
+#+end_src
+
+to run the Memory monitor plugin with the specified template, and the
+swap monitor plugin, with default options, every second. And here's an
+example of a template for the commands above using an icon:
+
+#+begin_src haskell
+  template="<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"
+#+end_src
+
+This example will run "xclock" command when date is clicked:
+
+#+begin_src haskell
+  template="<action=`xclock`>%date%</action>
+#+end_src
+
+The only internal available command is =Com= (see below Executing
+External Commands). All other commands are provided by plugins. xmobar
+comes with some plugins, providing a set of system monitors, a standard
+input reader, an Unix named pipe reader, a configurable date plugin, and
+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.
+
+** =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 [[http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Hooks-DynamicLog.html][here]]):
+
+  #+begin_src haskell
+    main = do
+      spawn "xmobar"
+      xmonad $ defaultConfig {
+        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 $ defaultConfig {
+      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 2
+optional ones (alias and rate):
+
+#+begin_src haskell
+  start :: e -> (String -> IO ()) -> IO ()
+  run   :: e -> IO String
+  rate  :: e -> Int
+  alias :: e -> String
+#+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 =examples/xmobar.hs= for an example
+of a plugin that runs just once, and =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
+0.11.1. Since then, it is maintained and developed by [[https://jao.io][jao]], with the help
+of the greater xmobar and Haskell communities.
+
+In particular, xmobar incorporates patches by Mohammed Alshiekh, Alex
+Ameen, Axel Angel, Dhananjay Balan, Claudio Bley, Dragos Boca, Ben
+Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick Chilton,
+Antoine Eiche, Nathaniel Wesley Filardo, John Goerzen, Reto Hablützel,
+Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost,
+Jochen Keil, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry
+Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry
+Malikov, David McLean, Marcin Mikołajczyk, Dino Morelli, Tony Morris,
+Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner,
+Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr
+Rockai, Andrew Emmanuel Rosa, Sackville-West, Markus Scherer, Daniel
+Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov,
+Peter Simons, Alexander Solovyov, Will Song, John Soros, Felix Springer,
+Travis Staton, Artem Tarasov, Samuli Thomasson, Edward Tjörnhammar,
+Sergei Trofimovich, Thomas Tuegel, John Tyree, Jan Vornberger, Anton
+Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun Hu, Edward Z. Yang and
+Norbert Zeh.
+
+** Thanks
+
+*Andrea Rossato*:
+
+Thanks to Robert Manea and Spencer Janssen for their help in
+understanding how X works. They gave me suggestions on how to solve many
+problems with xmobar.
+
+Thanks to Claus Reinke for make me understand existential types (or at
+least for letting me think I grasp existential types...;-).
+
+*jao*:
+
+Thanks to Andrea for creating xmobar in the first place, and for giving
+me the chance to contribute.
+
+* Related
+
+- To understand the internal mysteries of xmobar you may try reading
+  [[http://www.haskell.org/haskellwiki/X_window_programming_in_Haskell][this tutorial]] on X Window Programming in Haskell.
+
+* License
+
+This software is released under a BSD-style license. See [[https://github.com/jaor/xmobar/raw/master/license][license]] for
+more details.
+
+Copyright © 2010-2020 Jose Antonio Ortega Ruiz
+
+Copyright © 2007-2010 Andrea Rossato