Update README

1 files changed, 474 insertions, 129 deletions

@@ -42,14 +42,15 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
 
 ## Original init.el
 
-        ;; This file replaces itself with the actual configuration when
-        ;; first run.  To keep only this version in git, run this command:
-        ;;
-        ;; git update-index --assume-unchanged init.el
-        ;;
-        ;; If it needs to be changed, start tracking it again thusly:
-        ;;
-        ;; git update-index --no-assume-unchanged init.el
+This file replaces itself with the actual configuration when it's first run.  For easy installation, *this* is the `init.el` file in git – and you probably want to keep it that way.  To keep git from trying to update `init.el` when it's re-tangled, type this in the repo:
+
+        git update-index --assume-unchanged init.el
+
+If, for some reason, you want to change this original file to be re-tracked, run this command:
+
+        git update-index --no-assume-unchanged init.el
+
+Otherwise, here's the actual, original `init.el` that tangles this Org file and gets us going.
 
         (require 'org)
         (find-file (concat user-emacs-directory "config.org"))
@@ -59,8 +60,15 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
         (byte-compile-file (concat user-emacs-directory "init.el"))
 
 
+### TODO What I should do instead
+
+Honestly, I should just change this "Original init.el" thing to a Makefile I can tangle in `config.org`, and track – since it won't be overwritten or need any special `git` invocations to stop tracking it, I can edit it as I think about what would work best.  I could also maybe give it more of a "cross-platform" vibe by installing, say, `straight.el` in the Makefile on Windows.  One day …
+
+
 ## Tangling
 
+After our first tangle, each time we edit `config.org` we want to go ahead and re-tangle our config.  To that end, I've written `acdw/tangle-init`, which automatically tangles `config.org`.
+
         (defun acdw/tangle-init ()
           "If the current buffer is `config.org', tangle it, then compile
         and load the resulting files."
@@ -80,8 +88,12 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
                    (acdw/load-init)
                    (message "Tangled and loaded: %s" response)))))
 
+Since I want to tangle every time I save `config.org`, I've added `acdw/tangle-init` to a hook.
+
         (add-hook 'after-save-hook #'acdw/tangle-init)
 
+Finally, I want an easier way to load the generated init files than the old `M-x load-file RET ~/.config/emacs/init.el RET`.  So I've written `acdw/load-init` – which also gets called at the end of the async part of `acdw/tangle-init`.
+
         (defun acdw/load-init ()
           (interactive)
           (load-file (expand-file-name
@@ -95,25 +107,35 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
 
 ### Add directories to `load-path`
 
+I also put lispy stuff in the `lisp/` subdirectory of my Emacs config, and under my SyncThing directory (for easy syncing ;P).
+
         (dolist (dir `(,(concat user-emacs-directory
                         (convert-standard-filename "lisp/"))
                ,(expand-file-name "~/Sync/elisp/")))
           (add-to-list 'load-path dir))
 
 
-### Require my secrets
+### TODO Require my secrets
+
+While this is like, the *dumbest* way to do this, it's what I'm doing right now.  I'm going to slap a TODO on here because I really should make it better – like, `auth-sources` hooked into KeePassXC somehow… ?  Maybe follow [Bill Dietrich's setup](https://www.billdietrich.me/Authentication.html?expandall=1#KeePassXCandSecretService).
 
         (require 'acdw-secrets)
 
 
 # Early initiation
 
+Starting with version 27.1, Emacs loads `early-init.el` *before* `init.el`, setting up early stuff like package management, etc.  Since I use an alternative package manager, I have to bootstrap it here.
+
+Of course, I also want to set some really early-on settings here too, like `load-prefer-newer` – why not?
+
         ;; early-init.el -*- lexical-binding: t; no-byte-compile: t -*-
           (setq load-prefer-newer t)
 
 
 ## Increase the garbage collector
 
+Let's try to speed startup times by increasing the garbage collector's threshold while running init.  Note the hook afterwards that restores it to a reasonable default.
+
         (setq gc-cons-threshold (* 100 100 1000))
 
         (add-hook 'after-init-hook
@@ -123,16 +145,28 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
                      gc-cons-threshold)))
 
 
-## Add more paths to the `exec-path` when using Windows
+## Add more paths to the `exec-path`
+
+When using Windows (at work), I need to use the PortableGit installation I've downloaded, since I don't have Admin privileges.
 
         (when (eq system-type 'windows-nt)
-          (dolist (path '("~/bin"
-                  "C:/Users/aduckworth/Downloads/PortableGit/bin"
+          (dolist (path '("C:/Users/aduckworth/Downloads/PortableGit/bin"
                   "C:/Users/aduckworth/Downloads/PortableGit/usr/bin"))
                 (add-to-list 'exec-path path)))
 
+Elsewhere, I want to add a few more paths to the `exec-path` as well, since I store scripts in a couple of places at ~.
+
+        (dolist (path '("~/bin"
+                "~/.local/bin"
+                "~/Scripts"))
+          (add-to-list 'exec-path path))
+
 
-## Bootstrap `straight.el`
+## Bootstrap [straight.el](https://github.com/raxod502/straight.el)
+
+So far, this is the best package manager I've used.  It allows for *truly* declarative package management (if I don't specify a package here, it doesn't get loaded), easy installation from pretty much any source (as long as it's got a git repo), *and* it hooks into `use-package`!
+
+The one annoying thing is that this bootstrap code doesn't work on Windows for some reason.  I'm too lazy to really try and figure out why, so when I need to bootstrap on Windows (pretty rare, TBH), I just [download the master-branch zip file](https://github.com/raxod502/straight.el/archive/master.zip) and extract it to `~/.emacs.d/straight/repos/`.
 
         (defvar bootstrap-version)
         (let ((bootstrap-file
@@ -149,13 +183,17 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
           (load bootstrap-file nil 'nomessage))
 
 
-## Use `use-package`
+## Use [use-package](https://jwiegley.github.io/use-package/)
+
+Like I said, `straight.el` hooks into `use-package` easily.  These two lines get the latter to use the former by default.
 
         (setq straight-use-package-by-default t)
         (straight-use-package 'use-package)
 
 
-## Keep `~/.emacs.d` tidy
+## Keep `~/.emacs.d` tidy with [no-littering](https://github.com/emacscollective/no-littering)
+
+I'll be honest – I don't really notice this package.  But I think that's the point.  It keeps Emacs (and packages) from throwing files all over the place, so I have a clean `ls -l`.  Since I want to run this code as early as possible, I use the `straight-use-package` form instead of `use-package`.
 
         (straight-use-package 'no-littering)
         (require 'no-littering)
@@ -164,7 +202,21 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
 ## Additional `use-package` keywords
 
 
-### `:custom-update`
+### [:custom-update](https://github.com/a13/use-package-custom-update)
+
+The `:custom-update` keyword lets me do this:
+
+        (use-package package
+          :custom-update
+          (package-list '(1 2 3)))
+
+instead of this:
+
+        (use-package package
+          :config
+          (add-to-list 'package-list '(1 2 3)))
+
+It's not … perfect, but it's kind of nice.
 
         (use-package use-package-custom-update
           :straight (use-package-custom-update
@@ -172,7 +224,9 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
              :repo "a13/use-package-custom-update"))
 
 
-## Setup async
+## Setup [async](https://github.com/jwiegley/emacs-async)
+
+I thought this was included in Emacs at first, but it's not – so we need to install and require it.
 
         (straight-use-package 'async)
         (require 'async)
@@ -183,6 +237,10 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
 
 ## Customizing variables
 
+I like `use-package` a lot, but I don't like using those shims you see in a lot of other Emacs configs where they use `(use-package emacs)` forms and stuff like that – it just feels dirty.  Plus, `straight` gets confused about those packages sometimes.  So, since I'm actually *configuring* Emacs in this Org file, which is nicely organized anyway, I can just set settings the old-school way.
+
+Except.  Using `setq` is actually *not* recommended any more, because `customize-set-variable` is more expressive and can include side-effects.  However, not all settings are customizable, *and* `customize-set-variable` is like, way longer to type.  So I've decided to write a little macro (my first!) to copy `use-package`'s `:custom` keyword, except … *outside* `use-package`.  I've called it `cuss`, because I have a terrible sense of humor.
+
         (defmacro cuss (var val)
           "Basically `use-package''s `:custom', but without using either."
           `(progn
@@ -190,9 +248,11 @@ It's highly likely that the WTFPL is completely incompatible with the GPL, for w
               ',var ,val)))
 
 
-# Theme
+# Theme: [Modus](https://protesilaos.com/modus-themes/)
+
+Protesilaos Stavrou's *excellent* theme pair.  At some point I'll probably write my own that's really minimal and does some funky stuff with faces, but until then, these really are the best I've used.
 
-I'm using the [Modus](https://protesilaos.com/modus-themes/) themes.
+The big `dolist` form is from [his documentation](https://protesilaos.com/modus-themes/#h:a897b302-8e10-4a26-beab-3caaee1e1193); it basically allows me to configure both themes before loading them.  I've tweaked his code a little to use `use-package`.
 
         (defmacro modus-themes-format-sexp (sexp &rest objects)
           `(eval (read (format ,(format "%S" sexp) ,@objects))))
@@ -200,33 +260,39 @@ I'm using the [Modus](https://protesilaos.com/modus-themes/) themes.
         (dolist (theme '("operandi" "vivendi"))
           (modus-themes-format-sexp
            (use-package modus-%1$s-theme
-                 :init
-                 (setq modus-%1$s-theme-slanted-constructs t
-           modus-%1$s-theme-bold-constructs t
-           modus-%1$s-theme-fringes 'subtle
-           modus-%1$s-theme-mode-line '3d
-           modus-%1$s-theme-syntax 'yellow-comments
-           modus-%1$s-theme-intense-hl-line nil
-           modus-%1$s-theme-intense-paren-match t
-           modus-%1$s-theme-links nil
-           modus-%1$s-theme-no-mixed-fonts nil
-           modus-%1$s-theme-prompts nil
-           modus-%1$s-theme-completions nil
-           modus-%1$s-theme-diffs nil
-           modus-%1$s-theme-org-blocks 'grayscale
-           modus-%1$s-theme-headings
-           '((1 . section)
-             (2 . line)
-             (t . rainbow-line-no-bold))
-           modus-%1$s-theme-variable-pitch-headings nil
-           modus-%1$s-theme-scale-headings t
-           modus-%1$s-theme-scale-1 1.1
-           modus-%1$s-theme-scale-2 1.15
-           modus-%1$s-theme-scale-3 1.21
-           modus-%1$s-theme-scale-4 1.27
-           modus-%1$s-theme-scale-5 1.33))
+                 :custom
+                 (modus-%1$s-theme-slanted-constructs t)
+                 (modus-%1$s-theme-bold-constructs t)
+                 (modus-%1$s-theme-fringes nil)
+                 (modus-%1$s-theme-mode-line '3d)
+                 (modus-%1$s-theme-syntax 'yellow-comments)
+                 (modus-%1$s-theme-intense-hl-line nil)
+                 (modus-%1$s-theme-intense-paren-match t)
+                 (modus-%1$s-theme-links nil)
+                 (modus-%1$s-theme-no-mixed-fonts nil)
+                 (modus-%1$s-theme-prompts nil)
+                 (modus-%1$s-theme-completions nil)
+                 (modus-%1$s-theme-diffs nil)
+                 (modus-%1$s-theme-org-blocks 'grayscale)
+                 (modus-%1$s-theme-headings
+                  '((1 . section)
+        (2 . line)
+        (t . rainbow-line)))
+                 (modus-%1$s-theme-variable-pitch-headings t)
+                 (modus-%1$s-theme-scale-headings t)
+                 (modus-%1$s-theme-scale-1 1.1)
+                 (modus-%1$s-theme-scale-2 1.15)
+                 (modus-%1$s-theme-scale-3 1.21)
+                 (modus-%1$s-theme-scale-4 1.27)
+                 (modus-%1$s-theme-scale-5 1.33)
+                 :custom-face
+                 (font-lock-comment-face
+                  ((t (:inherit (custom-comment italic variable-pitch))))))
            theme))
 
+
+## Theme changer
+
 I also want to switch themes between night and day.
 
         (use-package theme-changer
@@ -240,12 +306,16 @@ I also want to switch themes between night and day.
 # Simplify GUI
 
 
+<a id="orga685025"></a>
+
 ## Frame defaults
 
+I want no toolbar, menubar, or scrollbars (ideally I'd have a vertical scrollbar if necessary, but apparently that's too much to ask the Emacs devs); and fringes and window dividers 2 pixels wide.
+
         (cuss default-frame-alist
                   '((tool-bar-lines . 0)
         (menu-bar-lines . 0)
-        (vertical-scroll-bars . 'right)
+        (vertical-scroll-bars . nil)
         (horizontal-scroll-bars . nil)
         (right-divider-width . 2)
         (bottom-divider-width . 2)
@@ -255,6 +325,8 @@ I also want to switch themes between night and day.
 
 ## Minibuffer window/frame defaults
 
+Of course, on the minibuffer, I want to make sure there's no scrollbar &#x2013; even if I change my mind on `vertical-scroll-bars`, above.
+
         (cuss minibuffer-frame-alist
                   '((width . 80)
         (height . 2)
@@ -265,24 +337,50 @@ I also want to switch themes between night and day.
 
 ## Remove unneeded GUI elements
 
+The [Frame Defaults](#orga685025) section sets up the frame to be free of visual clutter, but *this* section allows us to toggle that clutter's visibility easily, with one call to each of these functions.
+
         (menu-bar-mode -1)
         (tool-bar-mode -1)
+        (scroll-bar-mode -1)
         (horizontal-scroll-bar-mode -1)
 
 
+## Tabs
+
+I'm kind of getting into Emacs tabs &#x2013; but I like not showing the `tab-bar` when there's only one.
+
+        (cuss tab-bar-show 1)
+
+        (cuss tab-bar-tab-name-function 'tab-bar-tab-name-current-with-count)
+
+        (tab-bar-mode 1)
+
+
 ## Word wrap and operate visually
 
+`global-visual-line-mode` is one of those which, in my opinion, should be a default.  There's only one place I don't want to wrap words, and that's in `dired`, which I can set individually in its config.
+
         (global-visual-line-mode 1)
 
 
 ## Modeline
 
+
+### [smart-mode-line](https://github.com/Malabarba/smart-mode-line)
+
         (use-package smart-mode-line
           :custom
           (sml/no-confirm-load-theme t)
           :config
           (sml/setup))
 
+
+### [rich-minority](https://github.com/Malabarba/rich-minority)
+
+`smart-mode-line` comes with `rich-minority` for taking care of minor modes in the modeline, so I'm not going to *also* use `diminish` or anything.  However, `rich-minority` has kind of a hinky way of adding modes to the whitelist, so I had to write my own function to do so.
+
+This confuration means that, by default, no minor modes are shown; if you want  a minor mode to be shown (like `word-count-mode` for me), call `(rm/whitelist-add "REGEXP")`.
+
         (defun rm/whitelist-add (regexp)
           "Add a REGEXP to the whitelist for `rich-minority'."
           (if (listp 'rm--whitelist-regexps)
@@ -309,6 +407,8 @@ from [Ergo Emacs](http://ergoemacs.org/emacs/emacs_stop_cursor_enter_prompt.html
 
 ## Show `^L` as a line
 
+I like using the form-feed character to separate pages, it turns out.  'Tis nice.  This package turns that character into a nice long line.
+
         (use-package form-feed
           :hook
           ((text-mode prog-mode) . form-feed-mode))
@@ -316,11 +416,18 @@ from [Ergo Emacs](http://ergoemacs.org/emacs/emacs_stop_cursor_enter_prompt.html
 
 ## Cursor
 
+I want my cursor to be a bar in focused windows, but a hollow box in non-focused windows.
+
         (cuss cursor-type 'bar)
         (cuss cursor-in-non-selected-windows 'hollow)
 
 
-# Fonts
+# Typesetting
+
+
+## Fonts
+
+This is the best way I've come up with to specify a number of different fonts that apply depending on what's applied.  To be honest, I didn't really come up with the `font-candidate` function, though &#x2013; I got it from the ["Testing if fonts are available?"](https://www.emacswiki.org/emacs/SetFonts#toc11) section of the SetFonts page on EmacsWiki.
 
 See [this StackExchange question and answer](https://emacs.stackexchange.com/questions/12351/when-to-call-find-font-if-launching-emacs-in-daemon-mode) for more information on why I have these font settings applied in a hook.
 
@@ -363,7 +470,9 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
         (add-hook 'focus-in-hook #'acdw/setup-fonts)
 
 
-## Unicode
+## [unicode-fonts](https://github.com/rolandwalker/unicode-fonts)
+
+This does something similar to the above code, but for the entirety of the Unicode field (I think).
 
         (use-package unicode-fonts
           :config
@@ -372,18 +481,49 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ## Variable pitch faces
 
+One reason I like the Modus themes so much is that they have *excellent* support for variable-pitch faces, and mixing them with fixed-pitch faces in, say, Org Mode.  That means I can enable `variable-pitch-mode` in all my `text-mode`-derived buffers.
+
         (add-hook 'text-mode-hook #'variable-pitch-mode)
 
 
+## Padding
+
+This has been taken from ["Ricing Org Mode"](https://lepisma.xyz/2017/10/28/ricing-org-mode/) &#x2013; of course, I want the typographic niceties everywhere.
+
+        (cuss line-spacing 0.1)
+
+
 # Ease of use
 
 
-## Selectrum & Prescient
+## Startup
+
+I want a minimal screen when I start Emacs.  Based on the beauty of configs like [Nicolas Rougier's](https://github.com/rougier/elegant-emacs) [splash screen](https://github.com/rougier/emacs-splash) [experiments](https://github.com/rougier/nano-emacs), I might try my hand at some kind of splash screen or dashboard &#x2013; but until then, a simple "Hi there!" will suffice 😎
+
+        (cuss inhibit-startup-buffer-menu t)
+        (cuss inhibit-startup-screen t)
+        (cuss initial-buffer-choice t)
+        (cuss initial-scratch-message ";; Hi there!\n")
+
+
+## Completing-read niceties
+
+`completing-read` is Emacs's selection-narrowing-slash-completion framework thing.  There's a bunch of packages for it, including `ido`, `icomplete`, `ivy`, and `helm`.  I use raxod52's `selectrum` and others, which *extend* without *clobbering* existing Emacs functionality.  Plus they seem to run faster, at least on Windows.
+
+
+### [selectrum](https://github.com/raxod502/selectrum)
+
+`selectrum` is the basic *sorting and selecting items from a list* functionality.  It's a drop-in replacement for `ido` or the really basic tab-completion Emacs has for, say, `find-file`.
 
         (use-package selectrum
           :config
           (selectrum-mode 1))
 
+
+### [prescient](https://github.com/raxod502/prescient.el)
+
+`prescient` helps `selectrum` be more intelligent about sorting the candidates in a list &#x2013; it's in charge of the *filtering and sorting* bit of `completing-read` and friends.  It has an algorithm that works well enough for me, though I keep hearing about [orderless](https://github.com/oantolin/orderless), enough to maybe try it as well sometime.
+
         (use-package prescient
           :config
           (prescient-persist-mode 1))
@@ -394,7 +534,44 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
           (selectrum-prescient-mode 1))
 
 
-## CtrlF
+### [consult](https://github.com/minad/cconsult)
+
+`consult` is the newest package I have with this setup, and it kind of brings the `selectrum` experience up to par with `ivy`'s &#x2013; it provides functions that list, say, recently used files *alongside* buffers, allow you to search lines and go to them, etc.  It seems pretty nice so far.
+
+By the way, the [Reddit announcement thread for consult](https://www.reddit.com/r/emacs/comments/k3c0u7) has a great comment by the author detailing [the differences between different completing-read implementations](https://www.reddit.com/r/emacs/comments/k3c0u7/consult_counselswiper_alternative_for/ge460z3/) that actually is what convinced me to try `consult`.
+
+        (use-package consult
+          :after (selectrum)
+          :straight (consult
+             :host github
+             :repo "minad/consult")
+          :bind (("C-x b" . consult-buffer)
+         ("C-x 4 b" . consult-buffer-other-window)
+         ("C-x 5 b" . consult-buffer-other-frame)
+         ("M-g o" . consult-outline)
+         ("M-g l" . consult-line)
+         ("M-y" . consult-yank-pop)
+         ("<help> a" . consult-apropos))
+          :init
+          (fset 'multi-occur #'consult-multi-occur)
+          (consult-annotate-mode)
+          :config
+          (setf (alist-get 'execute-extended-command consult-annotate-alist)
+        #'consult-annotate-command-full))
+
+
+### Ignore case
+
+I don't like holding the Shift key if I can help it.
+
+        (cuss completion-ignore-case t)
+        (cuss read-buffer-completion-ignore-case t)
+        (cuss read-file-name-completion-ignore-case t)
+
+
+## [ctrlf](https://github.com/raxod502/ctrlf)
+
+The biggest reason I use this over the default functionality of `C-s` is that `ctrlf-forward-*` wraps the search around by default.
 
         (use-package ctrlf
           :custom
@@ -408,22 +585,9 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
           (ctrlf-mode 1))
 
 
-## Startup
+## [which-key](https://github.com/justbur/emacs-which-key)
 
-        (cuss inhibit-startup-buffer-menu t)
-        (cuss inhibit-startup-screen t)
-        (cuss initial-buffer-choice t)
-        (cuss initial-scratch-message ";; Hi there!\n")
-
-
-## Ignore case
-
-        (cuss completion-ignore-case t)
-        (cuss read-buffer-completion-ignore-case t)
-        (cuss read-file-name-completion-ignore-case t)
-
-
-## Which key
+This package is really helpful for discovering functionality.  When I get more adept in my Emacs-fu, I might remove this.
 
         (use-package which-key
           :custom
@@ -434,8 +598,12 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ## Miscellaneous settings
 
+Maybe a better title for this section is **Other settings** &#x2013; or maybe I should put them somewhere else entirely.
+
 
-### Set view mode when in a read-only file
+### Set `view-mode` when in a read-only file
+
+`view-mode` gives easy-to-use keybindings, like Space for page-down, etc., which are nice to have when you can't edit the file anyway.
 
         (cuss view-read-only t)
 
@@ -447,22 +615,30 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ### Enable all functions
 
+By default, Emacs disables some commands, because NeWbIeS wOuLd GeT cOnFuSeD or some ish.  I just want to use the dang editor!
+
         (cuss disabled-command-function nil)
 
 
 ### Shorter confirmations
 
+Instead of making me type *yes* or *no*, just let me hit the *y* or *n* key.
+
         (fset 'yes-or-no-p #'y-or-n-p)
 
 
 ### Uniquify buffer names
 
+This names buffers with the same basename (e.g., `~/.config/emacs/config.org` and `~/.emacs.d/config.org`) in a better way than the default (`config.org<1>`, etc).
+
         (require 'uniquify)
         (cuss uniquify-buffer-name-style 'forward)
 
 
 ### Show buffer boundaries
 
+These little L-shaped graphics at the top and bottom of buffers don't do anything, but I like 'em.
+
         (cuss indicate-buffer-boundaries
                   '((top . right)
         (bottom . right)
@@ -471,23 +647,14 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ### Hippie expand
 
-        (global-set-key (kbd "M-/") 'hippie-expand)
-
+At some point, will probably replace with [company](https://company-mode.github.io/).
 
-### iBuffer
-
-        (global-set-key (kbd "C-x C-b") 'ibuffer)
-
-
-### Zap-up-to-char, not zap-to-char
-
-        (autoload 'zap-up-to-char "misc"
-          "Kill up to, but not including, ARGth occurrence of CHAR." t)
+        (global-set-key (kbd "M-/") 'hippie-expand)
 
-        (global-set-key (kbd "M-z") 'zap-up-to-char)
 
+### "[better defaults](https://git.sr.ht/~technomancy/better-defaults/tree/master/better-defaults.el)"
 
-### Other "[better defaults](https://git.sr.ht/~technomancy/better-defaults/tree/master/better-defaults.el)"
+Most of these come from technomancy's repo, linked above, just copy-pasted into here.
 
         (cuss save-interprogram-paste-before-kill t)
         (cuss apropos-do-all t)
@@ -496,15 +663,34 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
         (cuss visible-bell (not (string= (system-name) "larry")))
         (cuss ediff-window-setup-function #'ediff-setup-windows-plain)
 
+1.  Zap-up-to-char, not zap-to-char
+
+        Similarly to `ibuffer`, this is a Better default™.
+
+                (autoload 'zap-up-to-char "misc"
+                  "Kill up to, but not including, ARGth occurrence of CHAR." t)
+
+                (global-set-key (kbd "M-z") 'zap-up-to-char)
+
+2.  iBuffer
+
+        A Better Default™ for `C-x C-b`.  I don't really use this, but everyone says it's worth it, so it's there.
+
+                (global-set-key (kbd "C-x C-b") 'ibuffer)
+
 
 ### So-long-mode
 
+I figure, why not go ahead and make Emacs deal with really long lines better?  Can't hurt, right?
+
         (if (boundp 'global-so-long-mode)
                 (global-so-long-mode))
 
 
 ### Change `just-one-space` to `cycle-space`
 
+I keep forgetting to actually *use* this keybind (I think it's `M-SPC`?), but cycling spacing seems *way* more useful than the default `just-one-space` function.
+
         (defun acdw/cycle-spacing-1 ()
           (interactive)
           (cycle-spacing -1))
@@ -514,8 +700,12 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 # Persistence
 
+Honestly, persistence across sessions was one of the best things about my well-tuned Vim setup.  Here's where I try to repeat that with Emacs.
 
-## Auto-saves
+
+## Auto-saves with [super-save](https://github.com/bbatsov/super-save)
+
+The default `auto-save` functionality isn't &#x2026; *enough* for me.  I want to *actually* save the files, and I don't care about `#file#` stuff.  So &#x2026; I use this package.
 
         (use-package super-save
           :custom
@@ -527,6 +717,8 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ## Backup files
 
+To be honest, I probably don't need backup files at all.  At some point, I will probably delete this.
+
         (cuss backup-directory-alist
                   `((".*" . ,(no-littering-expand-var-file-name "backup/"))))
 
@@ -538,20 +730,26 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ## Recent files
 
-        (use-package recentf
-          :custom-update
-          (recentf-exclude
-           '(no-littering-var-directory
-                 no-littering-etc-directory))
-          :custom
-          (recentf-max-menu-items 100)
-          (recentf-max-saved-items 100)
-          :config
-          (recentf-mode 1))
+Since I apparently *only* edit my `config.org`, this is also probably not necessary &#x2013; I'd be better off just adding a `(find-file (concat (user-emacs-directory "config.org")))` at the end 😎
+
+But until then, it's really nice to have a `recentf` list.
+
+        (require 'recentf)
+
+        (add-to-list 'recentf-exclude
+             '(no-littering-var-directory
+               no-littering-etc-directory))
+
+        (cuss recentf-max-menu-items 100)
+        (cuss recentf-max-saved-items 100)
+
+        (recentf-mode 1)
 
 
 ### Easily navigate recent files
 
+Now I'm going through this, I might not need this function any more.  I'll have to see how `consult` goes.
+
         (defun recentf-find-file ()
           "Find a recent file using `completing-read'."
           (interactive)
@@ -564,31 +762,39 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ## Save places in visited files
 
-        (use-package saveplace
-          :custom
-          (save-place-file (no-littering-expand-var-file-name "places"))
-          (save-place-forget-unreadable-files (not
-                                       (eq system-type 'windows-nt))
-          :config
-          (save-place-mode 1)))
+        (require 'saveplace)
+
+        (cuss save-place-file (no-littering-expand-var-file-name "places"))
+
+        (cuss save-place-forget-unreadable-files
+                  (not (eq system-type 'windows-nt)))
+
+        (save-place-mode 1)
 
 
 ## Save history
 
-        (use-package savehist
-          :custom
-          (savehist-additional-variables
-           '(kill-ring
-                 search-ring
-                 regexp-search-ring))
-          (savehist-save-minibuffer-history t)
-          (history-length t)
-          (history-delete-duplicates t)
-          :config
-          (savehist-mode 1))
+        (require 'savehist)
+
+        (cuss savehist-additional-variables
+                  '(kill-ring
+        search-ring
+        regexp-search-ring))
 
+        (cuss savehist-save-minibuffer-history t)
 
-## Undo
+        (cuss history-length t)
+
+        (cuss history-delete-duplicates t)
+
+        (savehist-mode 1)
+
+
+## Undo: [undo-fu-session](https://gitlab.com/ideasman42/emacs-undo-fu-session)
+
+The other Killer Feature of Neovim when I used it was the perisistent undo.  I *think* this works the same.  Honestly, undo is giving me a little grief recently; I need to look into it.
+
+Note to self: if I *do* switch away from `undo-fu`, look at [undohist](https://github.com/emacsorphanage/undohist).
 
         (use-package undo-fu-session
           :after (no-littering undo-fu)
@@ -607,6 +813,8 @@ See [this StackExchange question and answer](https://emacs.stackexchange.com/que
 
 ## File encoding
 
+I just want to use UTF-8 everywhere, and end all files with UNIX line endings (`^J`, or `LF`).  Hell, even Windows Notepad correctly reads UNIX files nowadays (though of course you can't configure it to *save* the files in UNIX-mode).  However, since Emacs is ~40 years old, it has a billion different ways to set encodings.  This is my best attempt at setting everything up how I want it.
+
 I'm going to be honest &#x2013; most of this is a stab in the dark.
 
         (set-language-environment 'utf-8)
@@ -627,7 +835,9 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
         (add-hook 'find-file-hooks #'acdw/no-junk-please-were-unixish)
 
 
-## Undo
+## [undo-fu](https://gitlab.com/ideasman42/emacs-undo-fu)
+
+I've heard that Emacs' undo is weird, so here I am, trying to make it &#x2026;. *less* weird.  I keep forgetting I've installed this though, so I might uninstall it at some point.
 
         (use-package undo-fu
           :bind
@@ -635,7 +845,9 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
           ("C-?" . undo-fu-only-redo))
 
 
-## Find/replace
+## Find/replace: [visual-regexp](https://github.com/benma/visual-regexp.el)
+
+Another replacement for a Killer Feature in Neovim &#x2013; the ease of regexp find/replace was so wonderful, because I could easily see *what* I'd be changing with a `%s` command, as well as *how* it'd change.  This works&#x2026; pretty similarly.  It could be a little better.
 
         (use-package visual-regexp
           :bind
@@ -646,14 +858,20 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
 ## Visual editing
 
 
-### Volatile highlights
+### [volatile-highlights](https://github.com/k-talo/volatile-highlights.el)
+
+Highlights text changed by certain operations.
 
         (use-package volatile-highlights
           :config
           (volatile-highlights-mode 1))
 
 
-### Expand region
+### [expand-region](https://github.com/magnars/expand-region.el)
+
+I don't use this a *ton*, but not because it's not useful &#x2013; I just forget it's there sometimes.
+
+Basically, it allows you to do like a Kakoune-style incremental widening of the selection by semantic units.
 
         (use-package expand-region
           :bind
@@ -663,19 +881,25 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
 
 ## Clean up white space on save
 
+I'm not sure if I'll *keep* this forever, because in combination with `super-save` I lose the final "thinking spaces" when I shift contexts to another window.
+
         (add-hook 'before-save-hook #'whitespace-cleanup)
         (add-hook 'before-save-hook #'delete-trailing-whitespace)
 
 
 ## Automatically revert a file to what it is on disk
 
+Revert a buffer to reflect what's on disk if it's changed outside of Emacs.
+
         (global-auto-revert-mode 1)
 
 
 # Writing
 
+Configurations related to writing prose or verse.
+
 
-## Word count
+## Word count: [wc-mode](https://github.com/bnbeckwith/wc-mode)
 
         (use-package wc-mode
           :config
@@ -683,7 +907,9 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
           :hook text-mode)
 
 
-## Visual fill column mode
+## [visual-fill-column-mode](https://github.com/joostkremers/visual-fill-column)
+
+Center the text part of the frame within a `fill-column`-sized area in the frame as a whole.
 
         (use-package visual-fill-column
           :custom
@@ -698,7 +924,22 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
           (text-mode . visual-fill-column-mode))
 
 
-## Org mode
+### Fix mouse bindings
+
+In `visual-fill-column-mode`, mouse bindings on the margins don't work.  In fact, they don't work when *not* in `visual-fill-column-mode`.  Let's bind those bindings.
+
+        (bind-key [left-margin wheel-down] 'scroll-down-command)
+        (bind-key [right-margin wheel-down] 'scroll-down-command)
+
+        (bind-key [left-margin wheel-up] 'scroll-up-command)
+        (bind-key [right-margin wheel-up] 'scroll-up-command)
+
+
+## [org-mode](https://orgmode.org/)
+
+Pretty self-explanatory, I think&#x2026;
+
+I need to break this config up and like, comment it better.
 
         (use-package org
           :custom
@@ -707,10 +948,25 @@ I'm going to be honest &#x2013; most of this is a stab in the dark.
           (org-hide-emphasis-markers t)
           (org-fontify-done-headline t)
           (org-fontify-whole-heading-line t)
+          (org-fontify-quote-and-verse-blocks t)
           (org-hide-leading-stars t)
           (org-hidden-keywords '(author date title))
           (org-src-window-setup 'current-window)
-          (org-pretty-entities t))
+          (org-pretty-entities t)
+          (org-ellipsis " ⋯ "))
+
+
+### Make bullets look like centered dots
+
+from [zzamboni.org](https://zzamboni.org/post/beautifying-org-mode-in-emacs/)
+
+        (font-lock-add-keywords
+         'org-mode
+         '(("^ *\\([-+]\\) "
+                (0 (prog1 ()
+         (compose-region (match-beginning 1)
+                         (match-end 1)
+                         "•"))))))
 
 
 ### Enable markdown export
@@ -869,18 +1125,26 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 # Coding
 
+The Other Thing Emacs is Good For.
+
 
 ## Formatting
 
 
-### Indenting
+### Indenting: [aggressive-indent-mode](https://github.com/Malabarba/aggressive-indent-mode)
+
+This automagically indents code on every change, as opposed to `electric-indent-mode`, which only does when I like, hit `RET` or whatever.  As such, I can turn `electric-indent-mode` off.
 
         (use-package aggressive-indent
+          :init
+          (electric-indent-mode -1)
           :config
           (global-aggressive-indent-mode 1))
 
 
-### Smart tabs
+### [Smart tabs](https://github.com/jcsalomon/smarttabs)
+
+I really want to like, use tabs all the time.  But I thought the `smart-tabs` package author made some good points about using tabs for semantic indentation, and spaces for the rest.  So.
 
         (use-package smart-tabs-mode
           :custom
@@ -897,6 +1161,8 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 ### Prettify symbols mode
 
+By default, I think `prettify-symbols-mode` only changes `lambda` to `λ`.  I should, at some point, add some prettified symbols.
+
         (add-hook 'prog-mode-hook #'prettify-symbols-mode)
 
 
@@ -904,10 +1170,14 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 1.  `show-paren-style`
 
+        A `mixed` `show-paren-style` means that, when both parentheses are visible, it just highlights them.  If one is *not*, though, it highlights the entire block.
+
                 (cuss show-paren-style 'mixed)
                 (show-paren-mode 1)
 
-2.  Smartparens
+2.  [smartparens](https://github.com/Fuco1/smartparens)
+
+        Automagically close pairs and stuff.  See also [ParEdit](https://www.emacswiki.org/emacs/ParEdit) &#x2013; maybe test that one?
 
                 (use-package smartparens
                   :init
@@ -917,13 +1187,17 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
                   :hook
                   (prog-mode . acdw/setup-smartparens))
 
-3.  Rainbow delimiters
+3.  [rainbow-delimiters](https://github.com/Fanael/rainbow-delimiters)
+
+        Show different pairs of delimiters in diffferent colors.  Pretty!  Useful!
 
                 (use-package rainbow-delimiters
                   :hook (prog-mode . rainbow-delimiters-mode))
 
 
-### Rainbow mode
+### [rainbow-mode](https://elpa.gnu.org/packages/rainbow-mode.html)
+
+Show different colors *in that color*.  Useful!  Pretty!
 
         (use-package rainbow-mode
           :custom
@@ -933,6 +1207,8 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 ### Line numbers
 
+I only want line numbers in `prog-mode`-derived modes.  In addition, apparently `linum-mode` works better in TUI, but is slower that `display-line-numbers`.  So I want to do some logic to see what to use.
+
         (defun acdw/enable-line-numbers ()
           "Enable line numbers, either through `display-line-numbers-mode'
         or through `linum-mode'."
@@ -948,6 +1224,8 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 ## Programming languages
 
+These are the programming languages I (don't really) use.
+
 
 ### Fish shell
 
@@ -1001,14 +1279,25 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 # Applications
 
+Of course, the real reason we love emacs is for the application layer.  What is it they say?
+
+> Emacs is a great operating system, lacking only a decent editor.
+
+Yeah, that's it 😎
+
 
-## Git
+## Git: [magit](https://magit.vc/)
+
+The magical porcelain.
 
         (use-package magit
           :bind
           ("C-x g" . magit-status)
           :custom-update
-          (magit-no-confirm '(stage-all-changes)))
+          (magit-no-confirm '(stage-all-changes))
+          :config
+          (add-hook 'magit-process-find-password-functions
+            #'magit-process-password-auth-source))
 
 
 ### Hook into `prescient`
@@ -1044,6 +1333,8 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
 
 ## Dired
 
+I'm still figuring out what all I can do with `dired`.
+
         (with-eval-after-load 'dired
           (cuss dired-dwim-target t)
           (cuss dired-listing-switches "-alDh")
@@ -1052,8 +1343,20 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
           (bind-key "C-c w" #'wdired-change-to-wdired-mode 'dired-mode-map))
 
 
+### dired-subtree
+
+Part of the [dired-hacks](https://github.com/Fuco1/dired-hacks) package.
+
+        (use-package dired-subtree
+          :bind (:map dired-mode-map
+              (("i" . dired-subtree-insert)
+               (";" . dired-subtree-remove))))
+
+
 ## Proced
 
+The process editor.
+
         (defun acdw/setup-proced ()
           (variable-pitch-mode -1)
           (toggle-truncate-lines 1)
@@ -1062,7 +1365,14 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
         (add-hook 'proced-mode-hook #'acdw/setup-proced)
 
 
-## Elpher
+## Gemini (and gopher)
+
+
+### [elpher](https://thelambdalab.xyz/elpher/)
+
+Actually, `elpher` is the reason I started using Emacs.  So thanks, smol web denizens!
+
+Fun fact: these packages are *also* why I use `straight.el`, since they're none of them on GitHub.
 
         (use-package elpher
           :straight (elpher
@@ -1094,6 +1404,11 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
           :hook
           (elpher-mode . visual-fill-column-mode))
 
+
+### [gemini-mode](https://git.carcosa.net/jmcbray/gemini.el)
+
+A major mode for `text/gemini` files.  I've changed the headings to match Elpher's.
+
         (use-package gemini-mode
           :straight (gemini-mode
              :repo "https://git.carcosa.net/jmcbray/gemini.el.git")
@@ -1105,29 +1420,48 @@ from [unpackaged.el](https://github.com/alphapapa/unpackaged.el#org-return-dwim)
            ((t (:inherit (elpher-gemini-heading2)))))
           (gemini-heading-face3
            ((t (:inherit (elpher-gemini-heading3)))))
+          :init
+          (defun acdw/setup-gemini-mode ()
+                (visual-fill-column-mode 1)
+                (variable-pitch-mode -1))
           :hook
-          (gemini-mode . visual-fill-column-mode))
+          (gemini-mode . acdw/setup-gemini-mode))
+
+
+### [gemini-write](https://alexschroeder.ch/cgit/gemini-write/about/)
+
+Alex Schroeder's Emacs implementation of the Titan protocol.  This is why I use his Gemini server, [Phoebe](https://alexschroeder.ch/cgit/phoebe/)!
 
         (use-package gemini-write
           :straight (gemini-write
              :repo "https://alexschroeder.ch/cgit/gemini-write")
           :config
-          (add-to-list 'elpher-gemini-tokens
-               (acdw-secrets/elpher-gemini-tokens)))
+          (when (boundp 'acdw-secrets/elpher-gemini-tokens)
+                (add-to-list 'elpher-gemini-tokens
+                 acdw-secrets/elpher-gemini-tokens)))
+
+
+### [post-to-gemlog-blue](https://git.sr.ht/~acdw/post-to-gemlog-blue.el)
+
+My first (!) Emacs package, to allow posting to [gemlog.blue's web interface](https://gemlog.blue).  I don't use gemlog.blue any more, but if I didn't have this package, no one would 😎
 
         (use-package post-to-gemlog-blue
           :straight (post-to-gemlog-blue
              :repo "https://git.sr.ht/~acdw/post-to-gemlog-blue.el"))
 
 
-## Pastebin (0x0)
+## Pastebin: [0x0](https://git.sr.ht/~zge/nullpointer-emacs)
+
+Pastebins are so useful.  Now I can use them from Emacs.
 
         (use-package 0x0
           :custom
           (0x0-default-service 'ttm))
 
 
-## Mu4e
+## [mu4e](https://www.djcbsoftware.nl/code/mu/mu4e.html)
+
+I've just recently started (again) using mu4e.  We'll see how it goes.
 
         (when (executable-find "mu")
           (add-to-list 'load-path
@@ -1213,3 +1547,14 @@ if ! emacsclient -nc "$@" 2>/dev/null; then
         emacs --daemon
         emacsclient -nc "$@"
     fi
+
+
+# Appendix B: areas for further research
+
+-   [ebuku](https://github.com/flexibeast/ebuku) (of course, I'd need [buku](https://github.com/jarun/buku) as well) &#x2013; bookmarks
+-   [KeePassXC as Secret Service](https://www.billdietrich.me/Authentication.html?expandall=1#KeePassXCandSecretService)
+-   [Ignoramus](https://github.com/rolandwalker/ignoramus) &#x2013; this might not e necessary
+-   [Dynamic fonts](https://github.com/rolandwalker/dynamic-fonts) &#x2013; take a look @ this and compare with my fonts section
+-   [Simple clipboard integration](https://github.com/rolandwalker/simpleclip) &#x2013; test with Windows, maybe
+-   [visible mark](https://git.sr.ht/~iank/visible-mark) &#x2013; show where the marks are &#x2026;
+-   consider this Reddit thread: [speeding up magit](https://www.reddit.com/r/emacs/comments/k3xfa1/speeding_up_magit/)