Update doc headings

Ain't no flavor without the sass

README.md

@@ -2,10 +2,38 @@
 
 A tidy `$HOME` is a tidy mind.
 
+It takes a touch of madness to use nixOS. I arrived here because there are a few
+special computers in my life, local and remote, and maintaining them was
+busywork I wouldn't wish on my worst enemy. 
+
+Nix, with its luscious tendrils, drew me in with a promise of glorious
+reproducibility and declared its declarative-ness with enough chutzpah to make
+anime real again. So, with XDG conventions in hand, I set out to conquer my
+white whale and annihilate what vestiges of my social life remain.
+
 ## Quick start
 
 ```sh
 # Make sure your partitions are set up by this point
 git clone https://github.com/hlissner/dotfiles /etc/dotfiles
-HOST=hostname make
+HOST=hostname make install
 ```
+
++ `make` = `nixos-rebuild test`
++ `make switch` = `nixos-rebuild switch`
++ `make upgrade` = `nix-channel --update && nixos-rebuild switch`
++ `make install` = `nixos-generate-config --root $PREFIX && nixos-install
+  --root $PREFIX`
+
+## Overview
+
++ OS: NixOS 19.09
++ Shell: zsh
++ DE/WM: bspwm + polybar
++ Editor: [Doom Emacs][doom-emacs] (and occasionally [vim][vimrc])
++ Terminal: st + extensions
++ Browser: firefox (waiting for qutebrowser to mature)
+
+
+[doom-emacs]: https://github.com/hlissner/doom-emacs
+[vimrc]: https://github.com/hlissner/.vim

machines/ao.nix

@@ -1,4 +1,4 @@
-# Ao -- my home development server
+# Ao -- my home development and user-facing server
 
 { config, ... }:
 {

machines/kuro.nix

@@ -47,8 +47,10 @@
   services.xserver.wacom.enable = true;
   my.init = ''
     # lock tablet to main display
+    if xinput list --id-only "Wacom Intuos Pro S Pen stylus"; then
+      xinput map-to-output $(xinput list --id-only "Wacom Intuos Pro S Pen stylus") DVI-I-1
       xinput map-to-output $(xinput list --id-only "Wacom Intuos Pro S Pen eraser") DVI-I-1
       xinput map-to-output $(xinput list --id-only "Wacom Intuos Pro S Pen cursor") DVI-I-1
-    xinput map-to-output $(xinput list --id-only "Wacom Intuos Pro S Pen stylus") DVI-I-1
+    fi
   '';
 }

modules/browser/firefox.nix

@@ -1,5 +1,9 @@
-{ config, lib, pkgs, ... }:
+# modules/browser/firefox.nix --- https://www.mozilla.org/en-US/firefox
+#
+# Oh firefox, gateway to the interwebs, devourer of ram. Give onto me your
+# infinite knowledge and shelter me from ads.
 
+{ config, lib, pkgs, ... }:
 {
   my.packages = with pkgs; [
     firefox-bin (pkgs.writeScriptBin "firefox-private" ''

modules/browser/qutebrowser.nix

@@ -1,3 +1,8 @@
+# modules/browser/qutebrowser.nix --- https://github.com/qutebrowser/qutebrowser
+#
+# Qutebrowser is cute because it's not enough of a browser to be handsome.
+# Still, we can all tell he'll grow up to be one hell of a lady-killer.
+
 { config, lib, pkgs, ... }:
 {
   my.packages = [ pkgs.qutebrowser ];

modules/chat.nix

@@ -1,5 +1,7 @@
+# modules/chat.nix
+#
 # Even neckbeards have a social life. Not that I have one. A neckbeard, I mean.
-# But when I do have either, then discord and weechat (or Emacs) are my go-to.
+# But when I do have either, then discord and weechat are my go-to.
 
 { config, lib, pkgs, ... }:
 {

modules/daw.nix

@@ -1,7 +1,9 @@
-# I make music for my games. LMMS is my DAW. Fruityloops too, on my Windows
-# system, but I'm slowly phasing it out for open-source alternatives. When I'm
-# in the mood for a quick chiptune, I fire up sunvox instead -- it runs
-# absolutely anywhere, even on my ipad and phone.
+# modules/music.nix
+#
+# I make music for my games. LMMS is my DAW; or will be, once I've weened myself
+# off of Fruityloops. When I'm in the mood for a quicky I fire up sunvox
+# instead. It runs absolutely anywhere, even on my ipad and phone. As if I'd
+# ever need to.
 
 { config, lib, pkgs, ... }:
 {

modules/dev/cc.nix

@@ -1,5 +1,10 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/cc.nix --- C & C++
+#
+# I love C. I tolerate C++. I adore C with a few choice C++ features tacked on.
+# Liking C/C++ seems to be an unpopular opinion. It's my guilty secret, so don't
+# tell anyone pls.
 
+{ pkgs, ... }:
 {
   imports = [ ./. ];
 

modules/dev/clojure.nix

@@ -1,4 +1,8 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/clojure.nix --- https://clojure.org/
+#
+# I don't use clojure. Perhaps one day...
+
+{ pkgs, ... }:
 {
   my.packages = with pkgs; [
     clojure

modules/dev/default.nix

@@ -1,5 +1,6 @@
-{ config, lib, pkgs, ... }:
+# modules/dev --- common settings for dev modules
 
+{ pkgs, ... }:
 {
   my.packages = with pkgs; [
     gnumake

modules/dev/godot.nix

@@ -1,8 +1,9 @@
-# I gamedev as a hobby. For making games, I mainly use C++ or Rust (and
-# occasionally Lua). However, when I need to prototype an idea, I reach for
-# godot (or JS, if I want it to be playable for others).
+# modules/dev/godot.nix --- https://godotengine.org/
+#
+# Gamedev is my hobby. C++ or Rust are my main drivers (and occasionally Lua),
+# but to prototype (for 3D, mainly) I'll occasionally reach for godot.
 
-{ config, lib, pkgs, ... }:
+{ pkgs, ... }:
 {
   my.packages = with pkgs; [
     godot

modules/dev/love2d.nix

@@ -1,5 +1,10 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/love2d.nix --- https://love2d.org/
+#
+# Love is my favorite little game engine. I use it often for rapid prototyping
+# when godot is overkill and have the luxury of avoiding JS. I write my Love
+# games in moonscript to get around the idiosynchrosies of lua.
 
+{ pkgs, ... }:
 {
   my.packages = with pkgs; [
     love

modules/dev/node.nix

@@ -1,5 +1,9 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/node.nix --- https://nodejs.org/en/
+#
+# JS is one of those "when it's good, it's alright, when it's bad, it's a
+# disaster" languages.
 
+{ pkgs, ... }:
 {
   imports = [ ./. ];
 

modules/dev/python.nix

@@ -1,5 +1,10 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/python.nix --- https://godotengine.org/
+#
+# Python's ecosystem repulses me. The list of environment "managers" exhausts
+# me. The Py2->3 transition make trainwrecks jealous. But SciPy, NumPy, iPython
+# and Jupyter can have my babies. Every single one.
 
+{ lib, pkgs, ... }:
 {
   my = {
     packages = with pkgs; [

modules/dev/rust.nix

@@ -1,4 +1,13 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/rust.nix --- https://rust-lang.org
+#
+# Oh Rust. The light of my life, fire of my loins. Years of C++ has conditioned
+# me to believe there was no hope left, but the gods have heard us. Sure, you're
+# not going to replace C/C++. Sure, your starlight popularity has been
+# overblown. Sure, macros aren't namespaced, cargo bypasses crates.io, and there
+# is no formal proof of your claims for safety, but who said you have to solve
+# all the world's problems to be wonderful?
+
+{ lib, pkgs, ... }:
 {
   my = {
     packages = with pkgs; [

modules/dev/unity3d.nix

@@ -1,7 +1,8 @@
-# I don't often use Unity, but I've worked with others who do. I'll commonly
-# reach for it for group projects.
+# modules/dev/unity3d.nix --- https://unity.com
+#
+# I don't use Unity often, but when I do, it's in a team or with students.
 
-{ config, lib, pkgs, ... }:
+{ pkgs, ... }:
 {
   my.packages = with pkgs; [
     unity3d

modules/dev/zsh.nix

@@ -1,5 +1,11 @@
-{ config, lib, pkgs, ... }:
+# modules/dev/zsh.nix --- http://zsh.sourceforge.net/
+#
+# Shell script programmers are strange beasts. Writing programs in a language
+# that wasn't intended as a programming language. Alas, it is not for us mere
+# mortals to question the will of the ancient ones. If they want shell programs,
+# they get shell programs.
 
+{ pkgs, ... }:
 {
   my.packages = with pkgs; [
     shellcheck

modules/graphics.nix

@@ -1,7 +1,8 @@
-# It's difficult to be an artist/designer on Linux. I miss adobe and my tablets
-# don't work without a lot of heart-ache. I set up a second computer just for
-# adobe work (and gaming) to address this, so why do I install these programs on
-# linux? Because sometimes I need to do some quick work right there and then.
+# modules/graphics.nix
+#
+# The hardest part about switching to linux was sacrifices adobe. It is so bad I
+# have a second computer dedicated to adobe (and gaming). Still, I can still
+# manage half of my design work on open source alternatives.
 
 { config, lib, pkgs, ... }:
 {

modules/recording.nix

@@ -1,11 +1,8 @@
-# I use OBS to capture footage/stream and DaVinci Resolve for editing (on my
-# Windows system -- it will run on windows, but there is no way to automate its
-# installation, what with their devs regsitration-gating their free download).
+# modules/recording.nix
 #
-# I also use ffmpeg for small casts/gifs, but this module is for the heavy duty
-# stuff.
-#
-# This module is best paired with ./audio-editing.nix
+# OBS to capture footage/stream, DaVinci Resolve for editing (on my Windows
+# system -- it will run on linux, but it can't be automated on nix, what with
+# their devs registration-gating their free download).
 
 { config, lib, pkgs, ... }:
 {

modules/themes/aquanaut/default.nix

@@ -1,18 +1,17 @@
-# We trained for this. The waves shudder and glare at me through its bright
-# tapestry. The clouds see me off as gravity lures me in lazily. How long have I
-# been down here? I imagined Jenny leading the team back on a rescue mission and
-# it upsets me. It was not worth the risk. We knew what we signed up for.
+# We trained for this. The waves shudder. They glare at me through its bright
+# tapestry as I sink. How long have I been down here? I imagined Jenny leading
+# the team back to rescue me and it upsets me. It wasn't worth the risk. We knew
+# what we signed up for.
 #
-# I hear glass crack. The sea depths hold my waist in a vice. Its strength
-# squeezing between the kelvar pockets of my suit. It's hard to breathe. If I
-# cut off the oxygen supply perhaps it'd be a nicer way to go.
+# The sea's strength squeezes between the kelvar pockets of my suit. Glass
+# cracks. It's hard to breathe. Cutting off the oxygen might be a nicer way to
+# go...
 #
 # When did I get so creative?
 #
-# I can't see further than three feet. Snowflake fractures creep along my visor.
-# Would Jorgen be relieved to have a dorm bunk to himself? HQ packs us into our
-# subs like sardines. I'll miss his snoring. Maybe I'll catch up on all that
-# missed sleep.
+# I can't see further than three feet. Snowflakes fracture across my visor.
+# Jorgen better be happy he gets our room all to himself now. I'll miss his
+# snoring. Maybe now's the time to catch up on all that lost sleep.
 
 { config, pkgs, ... }:
 {

modules/vm.nix

@@ -1,4 +1,7 @@
-# For testing software or building my games for other OSes
+# modules/vm.nix
+#
+# For testing software or building it on other OSes. If I find out how to get
+# macOS on qemu/libvirt I'd be happy to leave virtualbox behind.
 
 { config, lib, pkgs, ... }:
 {