From 141e071d0d523a521e0e790efbb57a95854aaaed Mon Sep 17 00:00:00 2001 From: jao Date: Sun, 24 Jul 2022 16:12:39 +0100 Subject: documentation: header levels re-adjusted --- doc/plugins.org | 1892 +++++++++++++++++++++++++++---------------------------- 1 file changed, 946 insertions(+), 946 deletions(-) (limited to 'doc/plugins.org') diff --git a/doc/plugins.org b/doc/plugins.org index 4923b11..45c024c 100644 --- a/doc/plugins.org +++ b/doc/plugins.org @@ -39,1117 +39,1117 @@ plugins that let you interact and control xmobar from window managers. -*** Icon Patterns +** 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. == will be interpreted as - == 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, + 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. == will be interpreted as + == 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", "" - , "--" - , "--brightness-icon-pattern", "" - ] 30 - #+end_src + #+begin_src haskell + Run Brightness + [ "-t", "" + , "--" + , "--brightness-icon-pattern", "" + ] 30 + #+end_src - Will display =bright_0.xpm= to =bright_8.xpm= depending on current - brightness value. + Will display =bright_0.xpm= to =bright_8.xpm= depending on current + brightness value. -*** Default Monitor Arguments +** Default Monitor Arguments - These are the options available for all monitors: + These are the options available for all monitors: - - =-t= /string/ Output template + - =-t= /string/ Output template - - Template for the monitor output. Field names must be enclosed - between pointy brackets (==) 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 - == (or ==) and ==. The rest of - the template is output verbatim. - - Long option: =--template= - - Default value: per monitor (see above). + - Template for the monitor output. Field names must be enclosed + between pointy brackets (==) 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 + == (or ==) and ==. The rest of + the template is output verbatim. + - Long option: =--template= + - Default value: per monitor (see above). - - =-H= /number/ The high threshold. + - =-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 + - 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. + - =-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 + - 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. + - =-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). + - 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 + - =-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). + - 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 + - =-l= /color/ The low threshold color - - Color for displaying values below the low threshold. - - Long option: =--low= - - Default: none (use the default foreground). + - Color for displaying values below the low threshold. + - Long option: =--low= + - Default: none (use the default foreground). - - =-S= /boolean/ Display optional suffixes + - =-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. + - 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 + - =-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) + - 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 + - =-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) + - 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 + - =-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 + - 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 + - =-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) + - 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 + - =-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) + - 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 + - =-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) + - 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 + - =-T= /number/ Maximum total width - - Maximum total width of the text. - - Long option: =--maxtwidth= - - Default: 0 (no limit) + - Maximum total width of the text. + - Long option: =--maxtwidth= + - Default: 0 (no limit) - - =-E= /string/ Maximum total width ellipsis + - =-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) + - Ellipsis to be added to the total text when it has reached its max + width. + - Long option: =--maxtwidthellipsis= + - Default: "" (no ellipsis) - - =-c= /string/ + - =-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: " " + - 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 + - =-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) + - 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 + - =-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: ":" + - 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 + - =-f= /string/ Bar foreground - - Characters used, cyclically, to draw the foreground of bars. - - Long option: =--bfore= - - Default value: "#" + - Characters used, cyclically, to draw the foreground of bars. + - Long option: =--bfore= + - Default value: "#" - - =-W= /number/ Bar width + - =-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. + - 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 + - =-x= /string/ N/A string - - String to be used when the monitor is not available - - Long option: =--nastring= - - Default value: "N/A" + - 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.: + Commands' arguments must be set as a list. E.g.: - #+begin_src haskell - Run Weather "EGPF" ["-t", ": C"] 36000 - #+end_src + #+begin_src haskell + Run Weather "EGPF" ["-t", ": 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: - 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 - #+begin_src shell - Glasgow Airport: 16.0C +** Battery Monitors +*** =Battery Args RefreshRate= + + Same as + + #+begin_src haskell + BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate #+end_src -*** Battery Monitors -***** =Battery Args RefreshRate= +*** =BatteryP Dirs Args RefreshRate= + :PROPERTIES: + :CUSTOM_ID: batteryp-dirs-args-refreshrate + :END: - Same as + - 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: , % / = + + - Example (note that you need "--" to separate regular monitor options + from Battery's specific ones): #+begin_src haskell - BatteryP ["BAT", "BAT0", "BAT1", "BAT2"] Args RefreshRate + Run BatteryP ["BAT0"] + ["-t", " (%)", + "-L", "10", "-H", "80", "-p", "3", + "--", "-O", "On - ", "-i", "", + "-L", "-15", "-H", "-5", + "-l", "red", "-m", "blue", "-h", "green", + "-a", "notify-send -u critical 'Battery running out!!'", + "-A", "3"] + 600 #+end_src -***** =BatteryP Dirs Args RefreshRate= - :PROPERTIES: - :CUSTOM_ID: batteryp-dirs-args-refreshrate - :END: - - - 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: , % / = - - - Example (note that you need "--" to separate regular monitor options - from Battery's specific ones): + In the above example, the thresholds before the =--= separator affect + only the == and == fields, while those after the + separator affect how == is displayed. For this monitor, neither + the generic nor the specific options have any effect on ==. + We are also telling the monitor to execute the unix command + =notify-send= when the percentage left in the battery reaches 6%. - #+begin_src haskell - Run BatteryP ["BAT0"] - ["-t", " (%)", - "-L", "10", "-H", "80", "-p", "3", - "--", "-O", "On - ", "-i", "", - "-L", "-15", "-H", "-5", - "-l", "red", "-m", "blue", "-h", "green", - "-a", "notify-send -u critical 'Battery running out!!'", - "-A", "3"] - 600 - #+end_src + It is also possible to specify template variables in the =-O= and =-o= + switches, as in the following example: - In the above example, the thresholds before the =--= separator affect - only the == and == fields, while those after the - separator affect how == is displayed. For this monitor, neither - the generic nor the specific options have any effect on ==. - 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", "" + , "-L", "10", "-H", "80" + , "-l", "red", "-h", "green" + , "--", "-O", "Charging", "-o", "Battery: %" + ] 10 + #+end_src - #+begin_src haskell - Run BatteryP ["BAT0"] - ["-t", "" - , "-L", "10", "-H", "80" - , "-l", "red", "-h", "green" - , "--", "-O", "Charging", "-o", "Battery: %" - ] 10 - #+end_src + - The "idle" AC state is selected whenever the AC power entering the + battery is zero. - - The "idle" AC state is selected whenever the AC power entering the - battery is zero. +*** =BatteryN Dirs Args RefreshRate Alias= -***** =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. +** Cpu and Memory Monitors +*** =Cpu Args RefreshRate= - 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. -*** Cpu and Memory Monitors -***** =Cpu Args RefreshRate= + - Aliases to =cpu= + - Args: default monitor arguments, plus: - - Aliases to =cpu= - - Args: default monitor arguments, plus: + - =--load-icon-pattern=: dynamic string for cpu load in =ipat= - - =--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: %= - - 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: %= +*** =MultiCpu Args RefreshRate= -***** =MultiCpu Args RefreshRate= + - Aliases to =multicpu= + - Args: default monitor arguments, plus: - - 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. - - =--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: %= - - 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: %= +*** =CpuFreq Args RefreshRate= -***** =CpuFreq Args RefreshRate= + - Aliases to =cpufreq= - - Aliases to =cpufreq= + - Args: default monitor arguments - - Args: default monitor arguments + - Thresholds refer to frequency in GHz - - Thresholds refer to frequency in GHz + - Variables that can be used with the =-t/--template= argument: + =cpu0=, =cpu1=, .., =cpuN=, give the current frequency of the + respective CPU core, and =max=, =min= and =avg= the maximum, minimum + and average frequency over all available cores. - - Variables that can be used with the =-t/--template= argument: - =cpu0=, =cpu1=, .., =cpuN=, give the current frequency of the - respective CPU core, and =max=, =min= and =avg= the maximum, minimum - and average frequency over all available cores. + - Default template: =Freq: GHz= - - Default template: =Freq: GHz= + - This monitor requires acpi_cpufreq module to be loaded in kernel - - This monitor requires acpi_cpufreq module to be loaded in kernel + - Example: - - Example: + #+begin_src haskell + Run CpuFreq ["-t", "Freq:|GHz", "-L", "0", "-H", "2", + "-l", "lightblue", "-n","white", "-h", "red"] 50 - #+begin_src haskell - Run CpuFreq ["-t", "Freq:|GHz", "-L", "0", "-H", "2", - "-l", "lightblue", "-n","white", "-h", "red"] 50 + Run CpuFreq ["-t", "Freq: GHz", "-L", "0", "-H", "2", + "-l", "lightblue", "-n","white", "-h", "red"] 50 + #+end_src - Run CpuFreq ["-t", "Freq: GHz", "-L", "0", "-H", "2", - "-l", "lightblue", "-n","white", "-h", "red"] 50 - #+end_src +*** =CoreTemp Args RefreshRate= -***** =CoreTemp Args RefreshRate= + - Aliases to =coretemp= - - Aliases to =coretemp= + - Args: default monitor arguments - - Args: default monitor arguments + - Thresholds refer to temperature in degrees - - Thresholds refer to temperature in degrees + - Variables that can be used with the =-t/--template= argument: + =core0=, =core1=, .., =coreN= - - Variables that can be used with the =-t/--template= argument: - =core0=, =core1=, .., =coreN= + - Default template: =Temp: C= - - Default template: =Temp: C= + - This monitor requires coretemp module to be loaded in kernel - - This monitor requires coretemp module to be loaded in kernel + - Example: - - Example: + #+begin_src haskell + Run CoreTemp ["-t", "Temp:|C", + "-L", "40", "-H", "60", + "-l", "lightblue", "-n", "gray90", "-h", "red"] 50 + #+end_src - #+begin_src haskell - Run CoreTemp ["-t", "Temp:|C", - "-L", "40", "-H", "60", - "-l", "lightblue", "-n", "gray90", "-h", "red"] 50 - #+end_src +*** =MultiCoreTemp Args RefreshRate= -***** =MultiCoreTemp Args RefreshRate= + - Aliases to =multicoretemp= - - Aliases to =multicoretemp= + - Args: default monitor arguments, plus: - - 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. + - =--hwmon-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. - - =--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. - - =--hwmon-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 - - 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= - - 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. - 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: °C - %= - - Default template: =Temp: °C - %= + - This monitor requires coretemp module to be loaded in kernel - - This monitor requires coretemp module to be loaded in kernel + - Example: - - Example: + #+begin_src haskell + Run MultiCoreTemp ["-t", "Temp: °C | %", + "-L", "60", "-H", "80", + "-l", "green", "-n", "yellow", "-h", "red", + "--", "--mintemp", "20", "--maxtemp", "100"] 50 + #+end_src - #+begin_src haskell - Run MultiCoreTemp ["-t", "Temp: °C | %", - "-L", "60", "-H", "80", - "-l", "green", "-n", "yellow", "-h", "red", - "--", "--mintemp", "20", "--maxtemp", "100"] 50 - #+end_src +*** =K10Temp Slot Args RefreshRate= -***** =K10Temp Slot Args RefreshRate= + - Aliases to =k10temp= - - Aliases to =k10temp= + - Slot: The PCI slot address of the k10temp device as a string. You + can find it as a subdirectory in =/sys/bus/pci/drivers/k10temp/=. - - Slot: The PCI slot address of the k10temp device as a string. You - can find it as a subdirectory in =/sys/bus/pci/drivers/k10temp/=. + - Args: default monitor arguments - - Args: default monitor arguments + - Thresholds refer to temperature in degrees - - Thresholds refer to temperature in degrees + - Variables that can be used with the =-t/--template= argument: + =Tctl=, =Tdie=, =Tccd1=, .., =Tccd8= - - Variables that can be used with the =-t/--template= argument: - =Tctl=, =Tdie=, =Tccd1=, .., =Tccd8= + - Default template: =Temp: C= - - Default template: =Temp: C= + - This monitor requires k10temp module to be loaded in kernel - - This monitor requires k10temp module to be loaded in kernel + - It is important to note that not all measurements are available + on on all models of processor. Of particular importance - Tdie + (used in the default template) may not be present on processors + prior to Zen (17h). Tctl, however, may be offset from the real + temperature and so is not used by default. - - It is important to note that not all measurements are available - on on all models of processor. Of particular importance - Tdie - (used in the default template) may not be present on processors - prior to Zen (17h). Tctl, however, may be offset from the real - temperature and so is not used by default. + - Example: - - Example: + #+begin_src haskell + Run K10Temp "0000:00:18.3" + ["-t", "Temp: C|C", + "-L", "40", "-H", "60", + "-l", "lightblue", "-n", "gray90", "-h", "red"] + 50 + #+end_src - #+begin_src haskell - Run K10Temp "0000:00:18.3" - ["-t", "Temp: C|C", - "-L", "40", "-H", "60", - "-l", "lightblue", "-n", "gray90", "-h", "red"] - 50 - #+end_src +*** =Memory Args RefreshRate= -***** =Memory Args RefreshRate= + - Aliases to =memory= + - Args: default monitor arguments, plus: - - 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=. + - =--scale=: sizes (total, free, etc.) are reported in units of + ~Mb/scale~, with scale defaulting to 1.0. So, for + instance, to get sizes reported in Gb, set this parameter + to 1024. - - =--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=. - - =--scale=: sizes (total, free, etc.) are reported in units of - ~Mb/scale~, with scale defaulting to 1.0. So, for - instance, to get sizes reported in Gb, set this parameter - to 1024. + - 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= - - 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: % (M)= - - Default template: =Mem: % (M)= + - Examples: - - Examples: + #+begin_src haskell + -- A monitor reporting memory used in Gb + Memory [ "-t", " Gb", "--", "--scale", "1024"] 20 + -- As above, but using one decimal digit to print numbers + Memory [ "-t", " Gb", "-d", "1", "--", "--scale", "1024"] 20 + #+end_src - #+begin_src haskell - -- A monitor reporting memory used in Gb - Memory [ "-t", " Gb", "--", "--scale", "1024"] 20 - -- As above, but using one decimal digit to print numbers - Memory [ "-t", " Gb", "-d", "1", "--", "--scale", "1024"] 20 - #+end_src +*** =Swap Args RefreshRate= -***** =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: %= - - 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: %= +** Date Monitors +*** =Date Format Alias RefreshRate= -*** Date Monitors -***** =Date Format Alias RefreshRate= + - Format is a time format string, as accepted by the standard ISO C + =strftime= function (or Haskell's =formatCalendarTime=). Basically, + if =date +"my-string"= works with your command then =Date= will handle + it correctly. - - Format is a time format string, as accepted by the standard ISO C - =strftime= function (or Haskell's =formatCalendarTime=). Basically, - if =date +"my-string"= works with your command then =Date= will handle - it correctly. + - Timezone changes are picked up automatically every minute. - - Timezone changes are picked up automatically every minute. + - Sample usage: - - Sample usage: + #+begin_src haskell + Run Date "%a %b %_d %Y %H:%M:%S" "date" 10 + #+end_src - #+begin_src haskell - Run Date "%a %b %_d %Y %H:%M:%S" "date" 10 - #+end_src +*** =DateZone Format Locale Zone Alias RefreshRate= -***** =DateZone Format Locale Zone Alias RefreshRate= + A variant of the =Date= monitor where one is able to explicitly set the + time-zone, as well as the locale. - A variant of the =Date= monitor where one is able to explicitly set the - time-zone, as well as the locale. + - The format of =DateZone= is exactly the same as =Date=. - - The format of =DateZone= is exactly the same as =Date=. + - If =Locale= is =""= (the empty string) the default locale of the + system is used, otherwise use the given locale. If there are more + instances of =DateZone=, using the empty string as input for =Locale= + is not recommended. - - If =Locale= is =""= (the empty string) the default locale of the - system is used, otherwise use the given locale. If there are more - instances of =DateZone=, using the empty string as input for =Locale= - is not recommended. + - =Zone= is the name of the =TimeZone=. It is assumed that the time-zone + database is stored in =/usr/share/zoneinfo/=. If the empty string is + given as =Zone=, the default system time is used. - - =Zone= is the name of the =TimeZone=. It is assumed that the time-zone - database is stored in =/usr/share/zoneinfo/=. If the empty string is - given as =Zone=, the default system time is used. + - Sample usage: - - Sample usage: + #+begin_src haskell + Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10 + #+end_src +** Disk Monitors +*** =DiskU Disks Args RefreshRate= - #+begin_src haskell - Run DateZone "%a %H:%M:%S" "de_DE.UTF-8" "Europe/Vienna" "viennaTime" 10 - #+end_src -*** Disk Monitors -***** =DiskU Disks Args RefreshRate= + - Aliases to =disku= - - Aliases to =disku= + - Disks: list of pairs of the form (device or mount point, template), + where the template can contain ==, ==, ==, == + or ==, ==, ==, ==, ==, + == or == for total, free, used, free percentage + and used percentage of the given file system capacity. - - Disks: list of pairs of the form (device or mount point, template), - where the template can contain ==, ==, ==, == - or ==, ==, ==, ==, ==, - == or == for total, free, used, free percentage - and used percentage of the given file system capacity. + - Thresholds refer to usage percentage. - - Thresholds refer to usage percentage. + - Args: default monitor arguments. =-t/--template= is ignored. Plus - - 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=. - - =--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). - - Default template: none (you must specify a template for each file - system). + - Example: - - Example: + #+begin_src haskell + DiskU [("/", "/"), ("sdb1", "")] + ["-L", "20", "-H", "50", "-m", "1", "-p", "3"] + 20 + #+end_src - #+begin_src haskell - DiskU [("/", "/"), ("sdb1", "")] - ["-L", "20", "-H", "50", "-m", "1", "-p", "3"] - 20 - #+end_src +*** =DiskIO Disks Args RefreshRate= -***** =DiskIO Disks Args RefreshRate= + - Aliases to =diskio= - - Aliases to =diskio= + - Disks: list of pairs of the form (device or mount point, template), + where the template can contain ==, ==, == for + total, read and write speed, respectively, as well as ==, + ==, ==, which report number of bytes during the last + refresh period rather than speed. There are also bar versions of each: + ==, ==, ==, ==, ==, + ==, ==, ==, and ==; and + their "bytes" counterparts: ==, ==, + ==, ==, ==, ==, + ==, ==, and ==. - - Disks: list of pairs of the form (device or mount point, template), - where the template can contain ==, ==, == for - total, read and write speed, respectively, as well as ==, - ==, ==, which report number of bytes during the last - refresh period rather than speed. There are also bar versions of each: - ==, ==, ==, ==, ==, - ==, ==, ==, and ==; and - their "bytes" counterparts: ==, ==, - ==, ==, ==, ==, - ==, ==, and ==. + - Thresholds refer to speed in b/s - - Thresholds refer to speed in b/s + - Args: default monitor arguments. =-t/--template= is ignored. Plus - - Args: default monitor arguments. =-t/--template= is ignored. Plus + - =--total-icon-pattern=: dynamic string for total disk I/O in + ==. + - =--write-icon-pattern=: dynamic string for write disk I/O in + ==. + - =--read-icon-pattern=: dynamic string for read disk I/O in + ==. - - =--total-icon-pattern=: dynamic string for total disk I/O in - ==. - - =--write-icon-pattern=: dynamic string for write disk I/O in - ==. - - =--read-icon-pattern=: dynamic string for read disk I/O in - ==. + - Default template: none (you must specify a template for each file + system). - - Default template: none (you must specify a template for each file - system). + - Example: - - Example: + #+begin_src haskell + DiskIO [("/", " "), ("sdb1", "")] [] 10 + #+end_src - #+begin_src haskell - DiskIO [("/", " "), ("sdb1", "")] [] 10 - #+end_src +** Keyboard Monitors +*** =Kbd Opts= -*** Keyboard Monitors -***** =Kbd Opts= + - Registers to XKB/X11-Events and output the currently active keyboard + layout. Supports replacement of layout names. - - Registers to XKB/X11-Events and output the currently active keyboard - layout. Supports replacement of layout names. + - Aliases to =kbd= - - Aliases to =kbd= + - Opts is a list of tuples: - - Opts is a list of tuples: + - first element of the tuple is the search string + - second element of the tuple is the corresponding replacement - - first element of the tuple is the search string - - second element of the tuple is the corresponding replacement + - Example: - - Example: + #+begin_src haskell + Run Kbd [("us(dvorak)", "DV"), ("us", "US")] + #+end_src - #+begin_src haskell - Run Kbd [("us(dvorak)", "DV"), ("us", "US")] - #+end_src +*** =Locks= -***** =Locks= + - Displays the status of Caps Lock, Num Lock and Scroll Lock. - - Displays the status of Caps Lock, Num Lock and Scroll Lock. + - Aliases to =locks= - - Aliases to =locks= + - Example: - - Example: + #+begin_src haskell + Run Locks + #+end_src - #+begin_src haskell - Run Locks - #+end_src +** Load and Process Monitors +*** =Load Args RefreshRate= -*** Load and Process Monitors -***** =Load Args RefreshRate= + - Aliases to =load= - - Aliases to =load= + - Args: default monitor arguments. The low and high thresholds + (=-L= and =-H=) refer to load average values. - - Args: default monitor arguments. The low and high thresholds - (=-L= and =-H=) refer to load average values. + - Variables that can be used with the =-t/--template= argument: + =load1=, =load5=, =load15=. - - Variables that can be used with the =-t/--template= argument: - =load1=, =load5=, =load15=. + - Default template: =Load: =. - - Default template: =Load: =. + - Displays load averages for the last 1, 5 or 15 minutes as + reported by, e.g., ~uptime(1)~. The displayed values are float, + so that the ~"-d"~ option will control how many decimal digits + are shown (zero by default). - - Displays load averages for the last 1, 5 or 15 minutes as - reported by, e.g., ~uptime(1)~. The displayed values are float, - so that the ~"-d"~ option will control how many decimal digits - are shown (zero by default). + - Example: to have 2 decimal digits displayed, with a low + threshold at 1.0 and a high one at 3, you'd write something + like: - - Example: to have 2 decimal digits displayed, with a low - threshold at 1.0 and a high one at 3, you'd write something - like: + #+begin_src haskell + Run Load ["-t" , " " + , "-L", "1", "-H", "3", "-d", "2"]) 300 + #+end_src - #+begin_src haskell - Run Load ["-t" , " " - , "-L", "1", "-H", "3", "-d", "2"]) 300 - #+end_src +*** =TopProc Args RefreshRate= -***** =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: == + - 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. - - 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: == - - 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= -***** =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: == + - 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. - - 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: == - - 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. +** Thermal Monitors +*** =ThermalZone Number Args RefreshRate= -*** Thermal Monitors -***** =ThermalZone Number Args RefreshRate= + - Aliases to "thermaln": so =ThermalZone 0 []= can be used in template + as =%thermal0%= - - Aliases to "thermaln": so =ThermalZone 0 []= can be used in template - as =%thermal0%= + - Thresholds refer to temperature in degrees - - Thresholds refer to temperature in degrees + - Args: default monitor arguments - - Args: default monitor arguments + - Variables that can be used with the =-t/--template= argument: =temp= - - Variables that can be used with the =-t/--template= argument: =temp= + - Default template: =C= - - Default template: =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). - - 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: - - Example: + #+begin_src haskell + Run ThermalZone 0 ["-t",": C"] 30 + #+end_src - #+begin_src haskell - Run ThermalZone 0 ["-t",": C"] 30 - #+end_src +*** =Thermal Zone Args RefreshRate= -***** =Thermal Zone Args RefreshRate= + - *This plugin is deprecated. Use =ThermalZone= instead.* - - *This plugin is deprecated. Use =ThermalZone= instead.* + - Aliases to the Zone: so =Thermal "THRM" []= can be used in template as + =%THRM%= - - Aliases to the Zone: so =Thermal "THRM" []= can be used in template as - =%THRM%= + - Args: default monitor arguments - - Args: default monitor arguments + - Thresholds refer to temperature in degrees - - Thresholds refer to temperature in degrees + - Variables that can be used with the =-t/--template= argument: =temp= - - Variables that can be used with the =-t/--template= argument: =temp= + - Default template: =Thm: C= - - Default template: =Thm: C= + - This plugin works only on systems with devices having thermal zone. + Check directories in /proc/acpi/thermal_zone for possible values. - - This plugin works only on systems with devices having thermal zone. - Check directories in /proc/acpi/thermal_zone for possible values. + - Example: - - Example: + #+begin_src haskell + Run Thermal "THRM" ["-t","iwl4965-temp: C"] 50 + #+end_src - #+begin_src haskell - Run Thermal "THRM" ["-t","iwl4965-temp: C"] 50 - #+end_src +** Volume Monitors +*** =Volume Mixer Element Args RefreshRate= -*** Volume Monitors -***** =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: - - 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 - - =-O= /string/ On string + - The string used in place of == when the mixer element is + on. Defaults to "[on]". + - Long option: =--on= - - The string used in place of == when the mixer element is - on. Defaults to "[on]". - - Long option: =--on= + - =-o= /string/ Off string - - =-o= /string/ Off string + - The string used in place of == when the mixer element is + off. Defaults to "[off]". + - Long option: =--off= - - The string used in place of == when the mixer element is - off. Defaults to "[off]". - - Long option: =--off= + - =-C= /color/ On color - - =-C= /color/ On color + - The color to be used for == when the mixer element is on. + Defaults to "green". + - Long option: =--onc= - - The color to be used for == when the mixer element is on. - Defaults to "green". - - Long option: =--onc= + - =-c= /color/ Off color - - =-c= /color/ Off color + - The color to be used for == when the mixer element is off. + Defaults to "red". + - Long option: =--offc= - - The color to be used for == 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. - - =--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= - - Long option: =--highv= + - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0. - - =-L= /number/ Low threshold for volume (in %). Defaults to 20.0. + - Long option: =--lowv= - - Long option: =--lowv= + - =-h=: /string/ High string - - =-h=: /string/ High string + - The string added in front of == when the mixer element is + on and the volume percentage is higher than the =-H= threshold. + Defaults to "". + - Long option: =--highs= - - The string added in front of == 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 - - =-m=: /string/ Medium string + - The string added in front of == when the mixer element is + on and the volume percentage is lower than the =-H= threshold. + Defaults to "". + - Long option: =--mediums= - - The string added in front of == 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 - - =-l=: /string/ Low string + - The string added in front of == when the mixer element is + on and the volume percentage is lower than the =-L= threshold. + Defaults to "". + - Long option: =--lows= - - The string added in front of == 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: % = + - 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. - - 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: % = - - 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= -***** =Alsa Mixer Element Args= + Like [[=Volume Mixer Element Args RefreshRate=][Volume]] but with the following differences: - 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=. - - 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=. +** Mail Monitors +*** =Mail Args Alias= -*** Mail Monitors -***** =Mail Args Alias= + - Args: list of maildirs in form =[("name1","path1"),...]=. Paths may + start with a '~' to expand to the user's home directory. - - 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. - - 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: - - Example: + #+begin_src haskell + Run Mail [("inbox", "~/var/mail/inbox"), + ("lists", "~/var/mail/lists")] + "mail" + #+end_src - #+begin_src haskell - Run Mail [("inbox", "~/var/mail/inbox"), - ("lists", "~/var/mail/lists")] - "mail" - #+end_src +*** =MailX Args Opts Alias= -***** =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. - - 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 - - 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. - - 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: - - Example: + #+begin_src haskell + Run MailX [("I", "inbox", "green"), + ("L", "lists", "orange")] + ["-d", "~/var/mail", "-p", " ", "-s", " "] + "mail" + #+end_src - #+begin_src haskell - Run MailX [("I", "inbox", "green"), - ("L", "lists", "orange")] - ["-d", "~/var/mail", "-p", " ", "-s", " "] - "mail" - #+end_src +*** =MBox Mboxes Opts Alias= -***** =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). - - 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 - - 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. - - 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. - - 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=: - - 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 - #+begin_src haskell - Run MBox [("I ", "inbox", "red"), ("O ", "~/foo/mbox", "")] - ["-d", "/var/mail/", "-p", " "] "mbox" - #+end_src +*** =NotmuchMail Alias Args Rate= -***** =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. - 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. - - Alias: What name the plugin should have in your template string. + - Args: A list of =MailItem= s of the form - - Args: A list of =MailItem= s of the form + #+begin_src haskell + [ MailItem "name" "address" "query" + ... + ] + #+end_src - #+begin_src haskell - [ MailItem "name" "address" "query" - ... - ] - #+end_src + where - 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*. - - =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). - - Rate: Rate with which to update the plugin (in deciseconds). + - Example: - - Example: + - A single =MailItem= that displays all unread threads from the given + address: - - A single =MailItem= that displays all unread threads from the given - address: + #+begin_src haskell + MailItem "mbs:" "soliditsallgood@mailbox.org" "" + #+end_src - #+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: - - 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 - #+begin_src haskell - MailItem "S:" "" "subject:[My-Subject]" - #+end_src + - A full example of a =NotmuchMail= configuration: - - 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 - #+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" +** Music Monitors +*** =MPD Args RefreshRate= - -- All unread mail that has @[Haskell-Cafe]@ in the subject line. - , MailItem "C:" "" "subject:[Haskell-Cafe]" + - 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). - -- 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 + - Aliases to =mpd= -*** Music Monitors -***** =MPD Args RefreshRate= + - 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: - - 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). + - =lapsed-icon-pattern=: dynamic string for current track position in + =ipat=. - - Aliases to =mpd= + - 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= - - 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: + - Default template: =MPD: = - - =lapsed-icon-pattern=: dynamic string for current track position in - =ipat=. + - Example (note that you need "--" to separate regular monitor options + from MPD's specific ones): - - 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= + #+begin_src haskell + Run MPD ["-t", + " (<album>) <track>/<plength> <statei> [<flags>]", + "--", "-P", ">>", "-Z", "|", "-S", "><"] 10 + #+end_src - - Default template: =MPD: <state>= +*** =MPDX Args RefreshRate Alias= - - Example (note that you need "--" to separate regular monitor options - from MPD's specific ones): + Like =MPD= but uses as alias its last argument instead of "mpd". - #+begin_src haskell - Run MPD ["-t", - "<composer> <title> (<album>) <track>/<plength> <statei> [<flags>]", - "--", "-P", ">>", "-Z", "|", "-S", "><"] 10 - #+end_src +*** =Mpris1 PlayerName Args RefreshRate= -***** =MPDX Args RefreshRate Alias= + - Aliases to =mpris1= - Like =MPD= but uses as alias its last argument instead of "mpd". + - 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. -***** =Mpris1 PlayerName Args RefreshRate= + - PlayerName: player supporting MPRIS v1 protocol. Some players need + this to be an all lowercase name (e.g. "spotify"), but some others + don't. - - Aliases to =mpris1= + - Args: default monitor arguments. - - 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. + - Variables that can be used with the =-t/--template= argument: + =album=, =artist=, =arturl=, =length=, =title=, =tracknumber= - - PlayerName: player supporting MPRIS v1 protocol. Some players need - this to be an all lowercase name (e.g. "spotify"), but some others - don't. + - Default template: =<artist> - <title>= - - Args: default monitor arguments. + - Example: - - Variables that can be used with the =-t/--template= argument: - =album=, =artist=, =arturl=, =length=, =title=, =tracknumber= + #+begin_src haskell + Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10 + #+end_src - - Default template: =<artist> - <title>= +*** =Mpris2 PlayerName Args RefreshRate= - - Example: + - Aliases to =mpris2= - #+begin_src haskell - Run Mpris1 "clementine" ["-t", "<artist> - [<tracknumber>] <title>"] 10 - #+end_src + - 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. -***** =Mpris2 PlayerName Args RefreshRate= + - PlayerName: player supporting MPRIS v2 protocol. Some players need + this to be an all lowercase name (e.g. "spotify"), but some others + don't. - - Aliases to =mpris2= + - Args: default monitor arguments. - - 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. + - Variables that can be used with the =-t/--template= argument: + =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=, + =composer=, =genre= - - PlayerName: player supporting MPRIS v2 protocol. Some players need - this to be an all lowercase name (e.g. "spotify"), but some others - don't. + - Default template: =<artist> - <title>= - - Args: default monitor arguments. + - Example: - - Variables that can be used with the =-t/--template= argument: - =album=, =artist=, =arturl=, =length=, =title=, =tracknumber=, - =composer=, =genre= + #+begin_src haskell + Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10 + #+end_src - - Default template: =<artist> - <title>= +** Network Monitors +*** =Network Interface Args RefreshRate= - - Example: + - Aliases to the interface name: so =Network "eth0" []= can be used as + =%eth0%= + - Thresholds refer to velocities expressed in B/s + - Args: default monitor arguments, plus: - #+begin_src haskell - Run Mpris2 "spotify" ["-t", "<artist> - [<composer>] <title>"] 10 - #+end_src + - =--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. -*** Network Monitors -***** =Network Interface Args RefreshRate= - - - Aliases to the interface name: so =Network "eth0" []= can be used as - =%eth0%= - - Thresholds refer to velocities expressed in B/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= + - 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= +*** =DynNetwork Args RefreshRate= - - Active interface is detected automatically - - Aliases to "dynnetwork" - - Thresholds are expressed in B/s - - Args: default monitor arguments, plus: + - Active interface is detected automatically + - Aliases to "dynnetwork" + - Thresholds are expressed in B/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. + - =--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=. + - 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 @@ -1157,73 +1157,73 @@ - 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. - -*** Weather Monitors - :PROPERTIES: - :CUSTOM_ID: weather-monitors - :END: -***** =Weather StationID Args RefreshRate= - - - Aliases to the Station ID: so =Weather "LIPB" []= can be used in - template as =%LIPB%= - - Thresholds refer to temperature in the selected units - - Args: default monitor arguments, plus: - - - =--weathers= /string/ : display a default string when the =weather= - variable is not reported. - - - short option: =-w= - - Default: "" - - - =--useManager= /bool/ : Whether to use one single manager per - monitor for managing network connections or create a new one every - time a connection is made. - - - Short option: =-m= - - Default: True - - - Variables that can be used with the =-t/--template= argument: - =station=, =stationState=, =year=, =month=, =day=, =hour=, - =windCardinal=, =windAzimuth=, =windMph=, =windKnots=, =windMs=, - =windKmh= =visibility=, =skyCondition=, =weather=, =tempC=, =tempF=, - =dewPointC=, =dewPointF=, =rh=, =pressure= - - Default template: =<station>: <tempC>C, rh <rh>% (<hour>)= - - Retrieves weather information from http://tgftp.nws.noaa.gov. Here is - an [[https://tgftp.nws.noaa.gov/data/observations/metar/decoded/CYLD.TXT][example]], also showcasing the kind of information that may be - extracted. Here is [[https://weather.rap.ucar.edu/surface/stations.txt][a sample list of station IDs]]. - -***** =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. + =["--", "--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. + +** Weather Monitors + :PROPERTIES: + :CUSTOM_ID: weather-monitors + :END: +*** =Weather StationID Args RefreshRate= + + - Aliases to the Station ID: so =Weather "LIPB" []= can be used in + template as =%LIPB%= + - Thresholds refer to temperature in the selected units + - Args: default monitor arguments, plus: + + - =--weathers= /string/ : display a default string when the =weather= + variable is not reported. + + - short option: =-w= + - Default: "" + + - =--useManager= /bool/ : Whether to use one single manager per + monitor for managing network connections or create a new one every + time a connection is made. + + - Short option: =-m= + - Default: True + + - Variables that can be used with the =-t/--template= argument: + =station=, =stationState=, =year=, =month=, =day=, =hour=, + =windCardinal=, =windAzimuth=, =windMph=, =windKnots=, =windMs=, + =windKmh= =visibility=, =skyCondition=, =weather=, =tempC=, =tempF=, + =dewPointC=, =dewPointF=, =rh=, =pressure= + - Default template: =<station>: <tempC>C, rh <rh>% (<hour>)= + - Retrieves weather information from http://tgftp.nws.noaa.gov. Here is + an [[https://tgftp.nws.noaa.gov/data/observations/metar/decoded/CYLD.TXT][example]], also showcasing the kind of information that may be + extracted. Here is [[https://weather.rap.ucar.edu/surface/stations.txt][a sample list of station IDs]]. + +*** =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: @@ -1249,85 +1249,85 @@ As mentioned, the replacement string can also be an icon specification, such as =("clear", "<icon=weather-clear.xbm/>")=. -*** Other Monitors -***** =Brightness Args RefreshRate= +** Other Monitors +*** =Brightness Args RefreshRate= - - Aliases to =bright= + - Aliases to =bright= - - Args: default monitor arguments, 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: actual_brightness) - - =-M=: file with the maximum brightness (default: max_brightness) - - =--brightness-icon-pattern=: dynamic string for current brightness - in =ipat=. + - =-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= + - Variables that can be used with the =-t/--template= argument: + =vbar=, =percent=, =bar=, =ipat= - - Default template: =<percent>= + - Default template: =<percent>= - - Example: + - Example: - #+begin_src haskell - Run Brightness ["-t", "<bar>"] 60 - #+end_src + #+begin_src haskell + Run Brightness ["-t", "<bar>"] 60 + #+end_src -***** =CatInt n filename= +*** =CatInt n filename= - - Reads and displays an integer from the file whose path is =filename= - (especially useful with files in =/sys=). + - 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. + - Aliases as =catn= (e.g. =Cat 0= as =cat0=, etc.) so you can have + several. - - Example: + - Example: - #+begin_src haskell - Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50 - #+end_src + #+begin_src haskell + Run CatInt 0 "/sys/devices/platform/thinkpad_hwmon/fan1_input" [] 50 + #+end_src -***** =CommandReader "/path/to/program" Alias= +*** =CommandReader "/path/to/program" Alias= - - Runs the given program, and displays its standard output. + - Runs the given program, and displays its standard output. -***** =Uptime Args RefreshRate= +*** =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= + - 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= -***** =UVMeter= +*** =UVMeter= - - Aliases to "uv" + station id. For example: =%uv Brisbane%= or - =%uv Alice Springs%= + - Aliases to "uv" + station id. For example: =%uv Brisbane%= or + =%uv Alice Springs%= - - Args: default monitor arguments, plus: + - 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. + - =--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 + - Short option: =-m= + - Default: True - - /Reminder:/ Keep the refresh rate high, to avoid making unnecessary - requests every time the plug-in is run. + - /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 + - Station IDs can be found here: + http://www.arpansa.gov.au/uvindex/realtime/xml/uvvalues.xml - - Example: + - Example: - #+begin_src haskell - Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900 - #+end_src + #+begin_src haskell + Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900 + #+end_src * Executing External Commands @@ -1365,7 +1365,7 @@ 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= + =ComX ProgramName Args ExitMessage Alias RefreshRate= Works like =Com=, but displaying =ExitMessage= (a string) if the execution fails. For instance: -- cgit v1.2.3