[polybar] Add module readme

polybar/.config/polybar/config

@@ -44,6 +44,10 @@ margin-top = 0
 margin-bottom = 0
 
 [bar/simple-top]
+; enable inter process communication, so that we can send messages
+; to polybar via polybar-msg command
+enable-ipc = true
+
 ; Put the bar at the bottom of the screen
 bottom=false
 
@@ -175,12 +179,12 @@ interval = 1.0
 ; To list all the zone types, run
 ; $ for i in /sys/class/thermal/thermal_zone*; do echo "$i: $(<$i/type)"; done
 ; Default: 0
-thermal-zone = 0
+thermal-zone = 2
 ; Use `sensors` to find preferred temperature source, then run
 ; $ for i in /sys/class/hwmon/hwmon*/temp*_input; do echo "$(<$(dirname $i)/name): $(cat ${i%_*}_label 2>/dev/null || echo $(basename ${i%_*})) $(readlink -f $i)"; done
 ; hwmon-path = /sys/devices/platform/coretemp.0/hwmon/hwmon0/temp1_input
 ; Base temperature for where to start the ramp (in degrees celsius)
-base-temperature = 40
+base-temperature = 50
 ; Threshold temperature to display warning label (in degrees celsius)
 warn-temperature = 70
 units = true
@@ -220,17 +224,19 @@ click-right = kill -USR2 %pid%
 ; display information on remaining papers to read for the upcoming week
 [module/papersdue]
 type = custom/script
-exec = $XDG_BIN_HOME/bib_due $BIBFILE | wc -l
-exec-if = type $XDG_BIN_HOME/bib_due
-click-left = tdrop -w "15%" -h $(echo "$(bib_due $BIBFILE | wc -l) * 25" | bc ) -x "45%" -y "15" -ma alacritty -e watch -t bib_due $BIBFILE
+exec = bib-due $BIBFILE | wc -l
+exec-if = type bib-due
+click-left = tdrop -w "15%" -h $(echo "$(bib-due $BIBFILE | wc -l) * 25" | bc ) -x "45%" -y "15" -ma alacritty -e watch -t bib-due $BIBFILE
 format-foreground = ${colors.primary}
-format-padding = 2
-format-prefix = " "
-interval = 2
+format-prefix = ""
+interval = 120
 
+; display unified available packages for update on arch from repos/aur
+; uses pacman-contrib/checkupdates if available to avoid partial arch upgrades
 [module/archupdates]
 type = custom/script
 exec = $XDG_CONFIG_HOME/polybar/scripts/poly-archupdates
+exec-if = type $XDG_CONFIG_HOME/polybar/scripts/poly-archupdates
 interval = 600
 format = <label>
 format-padding = 2

polybar/README.md

@@ -0,0 +1,81 @@
+# Polybar module
+
+[polybar](https://polybar.github.io/) - a fast and easy-to-use statusbar
+
+[[_TOC_]]
+
+## Polybar look
+
+minimal look:
+
+![minimal](.assets/polybar/minimal.png)
+
+Active i3 workspaces are displayed left with current workspace highlighted, and any active i3 modes. The center contains information on the currently playing song, displaying notes if something is playing, date and time, and upcoming bib readings from the library. The right contains system information and the task tray.
+
+with network activity:
+
+![network](.assets/polybar/network.png)
+
+full-load and temperature warning:
+
+![full](.assets/polybar/full.png)
+
+In general, the bar's colors are derived from the colors defined in xresources. It follows the base16 color template, as does every module in these dotfiles. That means the bar can be quickly re-themed using base16 color themes and the process can be automated (e.g. with styler).
+
+## i3 Workspaces
+
+![normal](.assets/polybar/i3-normal.png) -- focus on workspace 4
+
+The i3 workspaces module is pretty simple and self-explanatory. It shows all existing workspaces, and highlights the one that is currently active. It also highlights any workspaces on which an event took place.
+
+![highlight](.assets/polybar/i3-highlight.png) -- focus on workspace 2, workspace 1 highlighted
+
+Additionally, if an i3 mode is active, it will be displayed next to the workspaces in a stark color to notice the mode being active.
+
+![mode](.assets/polybar/i3-highlight.png) -- focus on workspace 3, 'Media' mode active
+
+Workspaces can be cycled with the mouse-wheel when hovering over the module, or can be invoked by clicking on the icons.
+
+## Current track information
+
+By default, the track information panel is very minimal. It simply displays a note when something is currently playing, a pause symbol when the current track is pause, and nothing at all when no track is currently available. (no media player open, all tracks stopped, etc.)
+
+When clicked, the track metadata is revealed, displaying track artist and title. Another click toggles it off again.
+
+![mpris](.assets/polybar/mpris.png)
+
+When right-clicked, the current track can be toggled between playing and paused.
+
+The `poly-mprisdisplay` script implementation requires `playerctl` available on the system to be run. It will return with an error message if the binary is not found. Symbols used can be easily customized in the script.
+
+## Date
+
+The standard polybar date display. Displays current date (DD/MM) and current time (24-hours) by default. On click, toggles to an expanded date display with current weekday and current week of the year.
+
+![clock](.assets/polybar/clock.png)
+
+![extended clock](.assets/polybar/clock_alt.png)
+
+## Upcoming Bib readings
+
+Depends on the [`bibtex`](bibtex/) module being installed, specifically a `$BIBFILE` variable pointing to the system library, and a `bib_due` script.
+
+Displays the library readings remaining for the week in simple numerical fashion. On click invokes the full `bib_due` script to show further information on the upcoming readings, requiring `dmenu` or `rofi` to display them.
+
+## System information
+
+Contains various system-relevant details.
+
+![system info](.assets/polybar/system.png)
+
+If the network has activity, it shows upload and download speeds (dynamically switching between displaying Kb/s, Mb/s). The script `poly-networkspeed` as of now uses hard-coded network interface names. If network interfaces have a different name, this will need to be adjusted.
+
+If updates for arch packages are available (from repositories or aur) it displays the number of available updates. The script `poly-archupdates` requires `yay` to be available. If checkupdates is available it will use this to check for repo packages, which can avoid partial arch updates in rare circumstances. (contained in `pacman-contrib` package)
+
+The volume module simply displays the current pulseaudio volume as a ramped version of the volume symbol. On click it toggles mute and un-mute.
+
+If xbacklight is available, the current display brightness is displayed as a symbol between a moon (dark) and a sun (bright).
+
+If a battery is available, it will display its current status,  percentage, and whether it is charging.
+
+The cpu load is displayed as a simple vertical bar, changing color at specific intervals to be more noticeable. When the cpu gets warm, a temperature warning will be displayed, along with current numeric temperature value (in °C). The correct sensor may have to be changed in the polybar config file; as well as useful limits for the display of temperature information.