Improving the documentation of monitor args

Following the discussion of pull request #59 in github.

1 files changed, 153 insertions, 137 deletions

diff --git a/readme.md b/readme.md
index 026e70a..f6b2af7 100644
--- a/readme.md
+++ b/readme.md
@@ -385,16 +385,138 @@ infrastructure. See below Writing a Plugin
 
 ## System Monitor Plugins
 
-This is the description of the system monitor plugins that are
-installed by default.
+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.
+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.
+
+
+### Default Monitor Arguments
+
+Monitors accept a common set of arguments, described in the first
+subsection below.  In additon, 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)
+- `-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)
+- `-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
+
+Commands' arguments must be set as a list. E.g.:
+
+    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 (see below). The low and high
+- 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
@@ -405,7 +527,7 @@ Monitors have default aliases.
 ### `Weather StationID Args RefreshRate`
 
 - Aliases to the Station ID: so `Weather "LIPB" []` can be used in template as `%LIPB%`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `station`, `stationState`, `year`, `month`, `day`, `hour`,
 	    `wind`, `visibility`, `skyCondition`, `tempC`, `tempF`,
@@ -418,7 +540,7 @@ Monitors have default aliases.
 
 - Aliases to the interface name: so `Network "eth0" []` can be used as
   `%eth0%`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
   `dev`, `rx`, `tx`, `rxbar`, `txbar`. Reception and transmission
   rates (`rx` and `tx`) are displayed in Kbytes per second, and you
@@ -430,7 +552,7 @@ Monitors have default aliases.
 
 - Aliases to the interface name with the suffix "wi": thus, `Wirelss
   "wlan0" []` can be used as `%wlan0wi%`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
             `essid`, `quality`, `qualitybar`
 - Default template: `<essid> <quality>`
@@ -441,7 +563,7 @@ Monitors have default aliases.
 ### `Memory Args RefreshRate`
 
 - Aliases to `memory`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
              `total`, `free`, `buffer`, `cache`, `rest`, `used`,
              `usedratio`, `usedbar`, `freebar`
@@ -450,7 +572,7 @@ Monitors have default aliases.
 ### `Swap Args RefreshRate`
 
 - Aliases to `swap`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `total`, `used`, `free`, `usedratio`
 - Default template: `Swap: <usedratio>%`
@@ -458,7 +580,7 @@ Monitors have default aliases.
 ### `Cpu Args RefreshRate`
 
 - Aliases to `cpu`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `total`, `bar`, `user`, `nice`, `system`, `idle`, `iowait`
 - Default template: `Cpu: <total>%`
@@ -466,7 +588,7 @@ Monitors have default aliases.
 ### `MultiCpu Args RefreshRate`
 
 - Aliases to `multicpu`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `autototal`, `autobar`, `autouser`, `autonice`,
 	    `autosystem`, `autoidle`, `total`, `bar`, `user`, `nice`,
@@ -487,7 +609,8 @@ Monitors have default aliases.
   look for the ACPI files of each battery. Example:
   `["BAT0","BAT1","BAT2"]`. Only the first 3 directories will be
   searched.
-- Args: default monitor arguments (see below), plus the following specif ones:
+- Args: default monitor arguments, plus the following
+  specific ones:
     - `-O`: string for AC "on" status (default: "On")
     - `-o`: string for AC "off" status (default: "Off")
     - `-L`: low power (`watts`) threshold (default: -12)
@@ -498,6 +621,8 @@ Monitors have default aliases.
     - `-p`: color to display positive power (battery charging)
     - `-f`: file in `/sys/class/power_supply` with AC info (default:
       "AC/online")
+  All this options, being specific to the monitor, are to be specified
+  after a `--` in the argument list (see example below).
 
 - Variables that can be used with the `-t`/`--template` argument:
 	    `left`, `leftbar`, `timeleft`, `watts`, `acstatus`
@@ -512,14 +637,17 @@ Monitors have default aliases.
                        "-L", "-15", "-H", "-5",
                        "-l", "red", "-m", "blue", "-h", "green"]
                       600
+
   In the above example, the thresholds before the "--" separator
-  refer to the `<left>` field, while those after the separator affect
-  how `<watts>` is displayed.
+  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>`.
 
 ### `TopProc Args RefreshRate`
 
 - Aliases to `top`
-- Args: default monitor arguments (see below). The low and high
+- 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
@@ -536,7 +664,7 @@ Monitors have default aliases.
 ### `TopMem Args RefreshRate`
 
 - Aliases to `topmem`
-- Args: default monitor arguments (see below). The low and high
+- 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:
@@ -553,7 +681,7 @@ Monitors have default aliases.
   where the template can contain <size>, <free>, <used>, <freep> or
   <usedp>, <freebar> or <usedbar> for total, free, used, free
   percentage and used percentage of the given file system capacity.
-- Args: default monitor arguments (see below). `-t`/`--template` is ignored.
+- Args: default monitor arguments. `-t`/`--template` is ignored.
 - Default template: none (you must specify a template for each file system).
 - Example:
 
@@ -567,7 +695,7 @@ Monitors have default aliases.
 - 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.
-- Args: default monitor arguments (see below). `-t`/`--template` is ignored.
+- Args: default monitor arguments. `-t`/`--template` is ignored.
 - Default template: none (you must specify a template for each file system).
 - Example:
 
@@ -577,7 +705,7 @@ Monitors have default aliases.
 
 - Aliases to "thermaln": so `ThermalZone 0 []` can be used in template
   as `%thermal0%`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `temp`
 - Default template: `<temp>C`
@@ -595,7 +723,7 @@ Monitors have default aliases.
 
 - Aliases to the Zone: so `Thermal "THRM" []` can be used in template
   as `%THRM%`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `temp`
 - Default template: `Thm: <temp>C`
@@ -608,7 +736,7 @@ Monitors have default aliases.
 ### `CpuFreq Args RefreshRate`
 
 - Aliases to `cpufreq`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `cpu0`, `cpu1`, ..,  `cpuN`
 - Default template: `Freq: <cpu0>GHz`
@@ -621,7 +749,7 @@ Monitors have default aliases.
 ### `CoreTemp Args RefreshRate`
 
 - Aliases to `coretemp`
-- Args: default monitor arguments (see below)
+- Args: default monitor arguments
 - Variables that can be used with the `-t`/`--template` argument:
 	    `core0`, `core1`, ..,  `coreN`
 - Default template: `Temp: <core0>C`
@@ -636,7 +764,7 @@ Monitors have default aliases.
 
 - 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 (see below). Also accepts:
+- 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]".
@@ -669,7 +797,7 @@ Monitors have default aliases.
 - 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 (see below). In addition you can provide
+- 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
@@ -765,7 +893,7 @@ Monitors have default aliases.
 ### `Brightness Args RefreshRate`
 
 - Aliases to `bright`
-- Args: default monitor arguments (see below), plus the following specif ones:
+- 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:
@@ -792,118 +920,6 @@ Monitors have default aliases.
 		Run Kbd [("us(dvorak)", "DV"), ("us", "US")]
 
 
-## Monitor Plugins Commands Arguments
-
-These are the arguments that can be used for internal commands in the
-`commands` configuration option:
-
-- `-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)
-- `-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)
-- `-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
-
-Commands' arguments must be set as a list. E.g.:
-
-    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
-
 ## Executing External Commands
 
 In order to execute an external command you can either write the