summaryrefslogtreecommitdiffhomepage
path: root/readme.md
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2012-08-19 14:50:45 +0200
committerJose Antonio Ortega Ruiz <jao@gnu.org>2012-08-19 14:56:58 +0200
commitc6ee412a0264607e5b91356bdee6605af0fd1cf5 (patch)
tree8fd65400e6414d9fa93116fd21a46af6c75529d5 /readme.md
parentb9f1711f8a00176e15e215608fabe019900edc10 (diff)
downloadxmobar-c6ee412a0264607e5b91356bdee6605af0fd1cf5.tar.gz
xmobar-c6ee412a0264607e5b91356bdee6605af0fd1cf5.tar.bz2
Improving the documentation of monitor args
Following the discussion of pull request #59 in github.
Diffstat (limited to 'readme.md')
-rw-r--r--readme.md290
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