Add documentation to mcrute.lua

2 files changed, 146 insertions, 59 deletions

diff --git a/.config/awesome/mcrute.lua b/.config/awesome/mcrute.lua
index f0a9bcd..b922b39 100644
--- a/.config/awesome/mcrute.lua
+++ b/.config/awesome/mcrute.lua
@@ -1,6 +1,19 @@
-local ipairs = ipairs
-local math = math
-
+-- AwesomeWM Customizations
+-- by Mike Crute <mike@crute.us>
+--
+-- This file contains the customizations that I run for AwesomeWM. I prefer to
+-- stick as close to the stock rc.lua file as possible so it's easier to
+-- upgrade. Over time awesome has had a habit of making drastic
+-- non-backwards-compatible changes to that file.
+--
+-- To understand some parts of this file it's useful to understand my runtime
+-- environment; I run both Fedora and Ubuntu depending on the context but
+-- always on a Dell XPS 13 (9370 and 9380). I don't run a traditional desktop
+-- environment nor do I run a settings daemon as they tend to be overly bloated
+-- and do much more than I care for so Awesome tends to subsume the important
+-- tasks (like display configuration) instead. I do depend heavily on systemd
+-- for user session task management.
+--
 local awful = require("awful")
 local beautiful = require("beautiful")
 local dpi = require("beautiful.xresources").apply_dpi
@@ -8,11 +21,17 @@ local gears = require("gears")
 local naughty = require("naughty")
 local wibox = require("wibox")
 
+-- Require this here because we customize it here but also so rc.lua can use it
+-- transitively through this module. It makes our local customizations to
+-- rc.lua just a little easier to grep for.
+local battery = require("battery")
+
 local timezone = "America/Los_Angeles"
 
 -- Good clear zoom stops for the Dell XPS 13 93{7,8}0
 local edp_zoom_modes = {
---    "2560x1440",
+-- "2880x1620",
+-- "2560x1440",
     "2048x1152",
     "1920x1080",
     "1600x900",
@@ -30,12 +49,14 @@ local edp_display_modes = {
     "1600x900",
     "1920x1080",
     "2048x1152",
+    "2560x1440",
     "2880x1620",
 }
 
 -- Preferred daily driver mode for the Dell XPS 13 93{7,8}0
 local default_edp_mode = edp_display_modes[3]
 
+-- dumps is a debugging tool that prints text representations of lua objects
 function dump(o)
     if type(o) == 'table' then
         local s = '{ '
@@ -49,6 +70,7 @@ function dump(o)
     end
 end
 
+-- string_split splits strings on a delimiter and returns a table of the parts
 function string_split(s, delimiter)
     if s == nil then
         return nil
@@ -60,9 +82,23 @@ function string_split(s, delimiter)
     return result
 end
 
+--
+-- Low Battery Warning
+--
 local battery_warning_delivered = false
 
-require("battery").status_callback = function(bat)
+-- Connects a battery status callback to the custom battery widget code. This
+-- gets called each time the status bar polls for battery status and is
+-- responsible for displaying a very prominent notification when the battery is
+-- running too low. It will display the warning once at 10% and then every
+-- polling interval at 5% and below. Below 5% the Dell battery drains much more
+-- rapidly than above that level and there's a chance it will either suspend or
+-- shut down (losing work in the case of the later).
+--
+-- This exists because I prefer to run my battery nearly to empty and then
+-- charge it to avoid excess wear on the battery. But I'd prefer to not lose
+-- work or be inconvenienced by a poorly timed suspend.
+battery.status_callback = function(bat)
     local should_warn = bat.charge <= 10 and (bat.status == 'discharging' or bat.status == 'not connected')
     local be_persistent =  bat.charge <= 5 and (bat.status == 'discharging' or bat.status == 'not connected')
 
@@ -89,7 +125,8 @@ require("battery").status_callback = function(bat)
     end
 end
 
--- TODO:
+-- TODO: Migrate tags from removed screen to free tags on remaining screens
+--
 -- https://www.reddit.com/r/awesomewm/comments/5r9mgu
 -- https://stackoverflow.com/questions/42056795
 function handle_tag_removal(tag)
@@ -113,7 +150,7 @@ function handle_tag_removal(tag)
 end
 
 -- TODO: Allow mouse resizing
--- Copy of suit.fair that forces rows to 1
+-- Copy of suit.fair that forces rows or columns to one
 local function do_equal(p, orientation)
     local wa = p.workarea
     local cls = p.clients
@@ -181,37 +218,38 @@ local function do_equal(p, orientation)
     end
 end
 
+-- setup_device_handling configures callbacks that need to be run when
+-- something changes about the system. This used to connect some dbus events to
+-- configure keyboards and mice but just does display management now.
 function setup_device_handling()
-    -- Refresh screen config when monitors are plugged and unplugged
     awesome.connect_signal("screen::change", configure_displays)
 end
 
-function setup_screens()
-end
-
+-- set_solid_wallpaper sets the gears wallpaper to a solid color as defined in
+-- beautiful.bg_normal
 function set_solid_wallpaper(s)
     wallpaper = gears.color.create_solid_pattern(beautiful.bg_normal)
     gears.wallpaper.set(wallpaper)
 end
 
+-- customize_theme applies additional customizations on the beautiful theme
+-- after it has been setup by rc.lua
 function customize_theme()
     beautiful.bg_urgent = "#222222"
     beautiful.border_width = dpi(0)
 
-    wallpaper_path_1 = gears.filesystem.get_dir("config") .. "tux-minimal-bg.png"
-    wallpaper_path_2 = os.getenv("HOME") .. "/Documents/personal/tux-minimal-bg.png"
-
-    if gears.filesystem.file_readable(wallpaper_path_1) then
-        beautiful.wallpaper = wallpaper_path_1
-    elseif gears.filesystem.file_readable(wallpaper_path_1) then
-        beautiful.wallpaper = wallpaper_path_2
+    -- Setup the wallpaper if it exists
+    wallpaper_path = gears.filesystem.get_dir("config") .. "tux-minimal-bg.png"
+    if gears.filesystem.file_readable(wallpaper_path) then
+        beautiful.wallpaper = wallpaper_path
     end
 
+    -- Setup custom icons for the custom equal layout in this file
     beautiful.layout_equalv = gears.filesystem.get_dir("config") .. "icons/equalvw.png"
     beautiful.layout_equalh = gears.filesystem.get_dir("config") .. "icons/equalhw.png"
 
+    -- Use a prettier icon theme if possible
     icon_theme_dir = "/usr/share/icons/Adwaita/"
-
     if gears.filesystem.dir_readable(icon_theme_dir) then
         naughty.config.icon_dirs = gears.table.join(naughty.config.icon_dirs, {
             icon_theme_dir
@@ -219,17 +257,27 @@ function customize_theme()
     end
 end
 
+-- start_desktop_target calls systemd to startup all the processes in the user
+-- session and hooks the quit function to properly shutdown systemd when
+-- awesome quits. This starts a desktop.target in the user mode systemd which
+-- can pull in widgets and anything else that enhances the desktop environment.
 function start_desktop_target()
     awful.spawn.spawn("systemctl --user start desktop.target")
 
-    awesome._awesome_quit = awesome.quit
-    awesome.quit = function()
-        awful.spawn.spawn("systemctl --user --wait stop desktop.target")
-        awesome._awesome_quit()
+    -- Only do this once in case awesome gets reloaded
+    if not awesome._awesome_quit then
+        awesome._awesome_quit = awesome.quit
+        awesome.quit = function()
+            -- The use of io.popen here is intentional because it will block until
+            -- systemd has finished stopping the target
+            io.popen("systemctl --user --wait stop desktop.target")
+            awesome._awesome_quit()
+        end
     end
 end
 
--- mcrute: use xprop to get this info
+-- add_window_rules mixes additional window rules into awful.rules.rules. To
+-- gather the information needed here use the xprop tool.
 function add_window_rules()
     awful.rules.rules = gears.table.join(awful.rules.rules, {
         { rule_any = {
@@ -248,10 +296,9 @@ function add_window_rules()
     })
 end
 
-function make_spawn(cmd)
-    return function() awful.util.spawn(cmd) end
-end
-
+-- move_mouse_top_right moves the mouse out of the way to the top right corner
+-- of the screen but avoids overlapping the layout picker because that displays
+-- a tooltip.
 function move_mouse_top_right()
     local mg = screen[mouse.screen].geometry
 
@@ -262,6 +309,12 @@ function move_mouse_top_right()
     })
 end
 
+-- zoom_screen uses xrandr to enable a lower resolution display mode and
+-- panning, mimicking at some level, the control scroll-wheel zooming that Mac
+-- OS is capable of.
+--
+-- This only works with the built-in display and not at all with external
+-- displays.
 function zoom_screen(zoom_stop)
     local mode = default_edp_mode
     local panning = "0x0"
@@ -282,8 +335,13 @@ function zoom_screen(zoom_stop)
     awful.util.spawn("xrandr --output eDP-1 --mode " .. mode .. " --panning " .. panning)
 end
 
+--
+-- Session-persistent Zooming Support
+--
 local current_zoom_stop = 0
 
+-- zoom_screen_up is a shortcut for zooming up using zoom stops that work
+-- correctly with the display
 function zoom_screen_up()
     if current_zoom_stop == #edp_zoom_modes then
         current_zoom_stop = #edp_zoom_modes
@@ -294,6 +352,8 @@ function zoom_screen_up()
     zoom_screen(current_zoom_stop)
 end
 
+-- zoom_screen_down is a shortcut for zooming down the screen using zoom stops
+-- that work correctly with the display
 function zoom_screen_down()
     if current_zoom_stop == 0 then
         zoom_screen(0)
@@ -303,12 +363,23 @@ function zoom_screen_down()
     end
 end
 
+-- zoom_screen_reset resets the zooming of the screen and disables panning
 function zoom_screen_reset()
     current_zoom_stop = 0
     zoom_screen(current_zoom_stop)
 end
 
+-- make_spawn is a shortcut for generating awful.util.spawn closures and allows
+-- using this shorthand in other places in this file.
+function make_spawn(cmd)
+    return function() awful.util.spawn(cmd) end
+end
+
+-- add_global_keys adds additional key bindings to the root key map. More
+-- specific documentation is inline with the function.
 function add_global_keys(globalkeys)
+    -- On Fedora this is installed with dnf; Ubuntu as of 18.04 doesn't package
+    -- light so it's built locally there.
     light = os.getenv("HOME") .. "/.local/bin/light"
     if not gears.filesystem.file_readable(light) then
         light = "light"
@@ -322,6 +393,8 @@ function add_global_keys(globalkeys)
         awful.key({                    }, "XF86AudioMicMute",       make_spawn("/usr/bin/pactl set-source-mute @DEFAULT_SOURCE@ toggle")),
 
         -- Audio Controls for Spotify
+        -- TODO: Make this work with rhythmbox and other stuff. Maybe not
+        --       needed at all if we can use some generic dbus functionality?
         awful.key({                    }, "XF86AudioPrev",          make_spawn("dbus-send --type=method_call --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player.Previous")),
         awful.key({                    }, "XF86AudioPlay",          make_spawn("dbus-send --type=method_call --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player.PlayPause")),
         awful.key({                    }, "XF86AudioNext",          make_spawn("dbus-send --type=method_call --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player.Next")),
@@ -332,31 +405,18 @@ function add_global_keys(globalkeys)
         awful.key({                    }, "XF86MonBrightnessUp",    make_spawn(light .. " -A 5")),
         awful.key({                    }, "XF86MonBrightnessDown",  make_spawn(light .. " -U 5")),
 
-        -- Suspend and Hibernate for Mac Keyboard
-        awful.key({ modkey, "Control"  }, "XF86Eject",              make_spawn("/usr/bin/sudo /bin/systemctl hibernate")),
-        awful.key({ modkey, "Shift"    }, "XF86Eject",              make_spawn("/usr/bin/sudo /bin/systemctl hybrid-sleep")),
-
-        -- Suspend and Hibernate for unpatched Mac Keyboard
-        awful.key({ modkey, "Control"  }, "F12",                    make_spawn("/usr/bin/sudo /bin/systemctl hibernate")),
-        awful.key({ modkey, "Shift"    }, "F12",                    make_spawn("/usr/bin/sudo /bin/systemctl hybrid-sleep")),
-
-        -- Hack for unpatched Mac Keyboard
-        -- awful.key({ modkey,            }, "F7",                     make_spawn("dbus-send --type=method_call --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player.Previous")),
-        -- awful.key({ modkey,            }, "F8",                     make_spawn("dbus-send --type=method_call --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player.PlayPause")),
-        -- awful.key({ modkey,            }, "F9",                     make_spawn("dbus-send --type=method_call --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player.Next")),
-        -- awful.key({ modkey,            }, "F10",                    make_spawn("/usr/bin/pactl set-sink-mute @DEFAULT_SINK@ toggle")),
-        -- awful.key({ modkey,            }, "F11",                    make_spawn("/usr/bin/pactl set-sink-volume @DEFAULT_SINK@ '-5%'")),
-        -- awful.key({ modkey,            }, "F12",                    make_spawn("/usr/bin/pactl set-sink-volume @DEFAULT_SINK@ '+5%'")),
+        -- Screen Zooming Commands
+        awful.key({ modkey             }, "z",                      zoom_screen_up),
+        awful.key({ modkey             }, "-",                      zoom_screen_down),
+        awful.key({ modkey             }, "=",                      zoom_screen_reset),
 
         -- Other useful commands
-        awful.key({ "Control", "Shift" }, "`",                      make_spawn("xscreensaver-command -lock")),
         awful.key({ modkey, "Shift"    }, "p",                      move_mouse_top_right),
-        awful.key({ modkey             }, "z",                      zoom_screen_up),
-        awful.key({ modkey             }, "-",                      zoom_screen_down),
-        awful.key({ modkey             }, "=",                      zoom_screen_reset)
+        awful.key({ "Control", "Shift" }, "`",                      make_spawn("xscreensaver-command -lock"))
     )
 end
 
+-- get_layouts returns layouts to be used for awful.layout.layouts
 function get_layouts()
     return {
         awful.layout.suit.tile,
@@ -370,6 +430,10 @@ function get_layouts()
     }
 end
 
+-- split_screen creates a virtual screen and splits the main screen in half.
+-- This is mostly useful for the ultra-widescreen curved monitors. It makes
+-- Awesome treat the monitor as containing two totally independent screens as
+-- if it were two different monitors.
 function split_screen(s)
     local geo = screen[s].geometry
     local new_width = math.ceil(geo.width/2)
@@ -379,10 +443,16 @@ function split_screen(s)
     screen.fake_add(geo.x + new_width, geo.y, new_width2, geo.height)
 end
 
+-- get_clock creates a textclock widget for the wibox. It's basically the
+-- defaults but overrides the timezone to account for some oddities that I was
+-- experiencing with Ubuntu when changing timezones.
 function get_clock()
     return wibox.widget.textclock(" %a %b %d, %H:%M ", 60, timezone)
 end
 
+-- pomodoro is a little pomodoro timer "app" that will show a notification on
+-- all screens with a picture of a tomato after 25 minutes. It facilitates
+-- using the pomodoro technique with nothing more than awesome.
 function pomodoro()
     local positions = {"bottom_right", "bottom_left", "bottom_right"}
 
@@ -404,15 +474,26 @@ function pomodoro()
     }
 end
 
+-- default_display_handler configures an output to use it's default xrandr mode
+-- and position it to the right of the laptop built-in display. This should be
+-- good enough for most screens.
 function default_display_handler(card, edp_mode)
     awful.util.spawn("xrandr --output eDP-1 --mode ".. edp_mode .. " --output " .. card .. " --auto --right-of eDP-1")
 end
 
+-- get_displays uses a shell script helper (~/bin/enumerate-displays) to
+-- retrieve a list of connected displays and their EDIDs. It will convert this
+-- into a table and return it.
+--
+-- The shell script exists mainly because Lua doesn't have any built-in ability
+-- to list directories unless you compile a C extension (won't work with
+-- awesome), use Glib (eww), or parse ls/find (error-prone).
 function get_displays()
     local result = {}
     local parts = nil
     local outputs = nil
 
+    -- TODO: Use the awful.spawn async functions
     -- Do this first to ensure /sys is up-to-date
     io.popen("xrandr -q"):close()
     outputs = io.popen(os.getenv("HOME") .. "/bin/enumerate-displays")
@@ -429,6 +510,15 @@ function get_displays()
     return result
 end
 
+-- configure_displays uses xrandr to configure the displays connected to the
+-- system when they are connected for removed.
+--
+-- This would normally be done by a settings daemon but since I don't run one
+-- we have to do it manually here. This function gets called as part of a
+-- screen::change signal.
+--
+-- TODO: This should be a lot more intelligent and a lot less hard coded but it
+-- works for what I do so *shrug*
 function configure_displays()
     local displays = get_displays()
 
@@ -442,8 +532,6 @@ function configure_displays()
         return
     end
 
-    -- TODO: This should be a lot more intelliegent and a lot less hard coded
-    -- but it works for what I do so *shrug*
     for _, s in pairs(displays) do
         if s.edid == "DELL U2715H" then -- 27" Dell monitors
             awful.util.spawn("xrandr " ..
@@ -464,19 +552,18 @@ function configure_displays()
 end
 
 return {
+    -- Public "API" used by rc.lua
     add_global_keys = add_global_keys,
     add_window_rules = add_window_rules,
-    battery_low_warning = battery_low_warning,
-    configure_displays = configure_displays,
     customize_theme = customize_theme,
-    dump = dump,
     get_clock = get_clock,
-    get_displays = get_displays,
     get_layouts = get_layouts,
-    pomodoro = pomodoro,
-    set_solid_wallpaper = set_solid_wallpaper,
     setup_device_handling = setup_device_handling,
-    split_screen = split_screen,
     start_desktop_target = start_desktop_target,
-    zoom_screen = zoom_screen,
+    battery = battery,
+
+    -- Public functions that are useful on import
+    configure_displays = configure_displays,
+    dump = dump,
+    pomodoro = pomodoro,
 }
diff --git a/.config/awesome/rc.lua b/.config/awesome/rc.lua
index 18676e9..3577384 100644
--- a/.config/awesome/rc.lua
+++ b/.config/awesome/rc.lua
@@ -17,7 +17,7 @@ local hotkeys_popup = require("awful.hotkeys_popup").widget
 -- Enable hotkeys help widget for VIM and other apps
 -- when client with a matching name is opened:
 require("awful.hotkeys_popup.keys")
-local battery = require("battery")
+-- See this file for more details about local customizations
 local mcrute = require("mcrute")
 
 mcrute.setup_device_handling()
@@ -171,7 +171,7 @@ awful.screen.connect_for_each_screen(function(s)
         { -- Right widgets
             layout = wibox.layout.fixed.horizontal,
             wibox.widget.systray(),
-            battery(),
+            mcrute.battery(),
             mytextclock,
             s.mylayoutbox,
         },