diff options
| -rw-r--r-- | readme.md | 288 |
1 files changed, 151 insertions, 137 deletions
@@ -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,15 @@ 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. ### `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 +662,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 +679,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 +693,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 +703,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 +721,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 +734,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 +747,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 +762,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 +795,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 +891,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 +918,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 |