Standardize module READMEs

modules/app/email/README.org

@@ -1,4 +1,4 @@
-* :app email
+#+TITLE: :app email
 
 This module makes Emacs an email client, using ~mu4e~.
 
@@ -10,41 +10,45 @@ It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email
 WARNING: my config is gmail/gsuite oriented, and since Google has its own opinions on the IMAP standard, it is unlikely to translate to other hosts.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+  - [[#macos][MacOS]]
+  - [[#arch-linux][Arch Linux]]
+- [[#dependencies][Dependencies]]
+
+* Install
 This module requires:
 
 + ~offlineimap~ (to sync mail with)
 + ~mu~ (to index your downloaded messages)
 
-*** MacOS
+** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew install mu --with-emacs
 brew install offlineimap
 #+END_SRC
 
-*** Arch Linux
+** Arch Linux
 #+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
 sudo pacman --noconfirm --needed -S offlineimap mu
 #+END_SRC
 
-** Dependencies
+* Dependencies
 You need to do the following:
 
-1. Write a ~\~/.offlineimaprc~. Mine can be found [[https://github.com/hlissner/dotfiles/tree/master/shell/+mu][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I use unix pass to securely store my login credentials.
+1. Write a ~\~/.offlineimaprc~. Mine can be found [[https://github.com/hlissner/dotfiles/tree/master/shell/+mu][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials.
 2. Download your email: ~offlineimap -o~ (may take a while)
 3. Index it with mu: ~mu index --maildir ~/.mail~
 
 Then configure Emacs to use your email address:
 
 #+BEGIN_SRC emacs-lisp :tangle no
-;; + %s is replaced with the label, e.g. /%s/Drafts => /lissner.net/Drafts
+;; Each path is relative to `+email-mu4e-mail-path', which is ~/.mail by default
-;; + Each path is relative to `+email-mu4e-mail-path', which is ~/.mail by
+(set! :email "Lissner.net"
-;;   default
+    '((mu4e-sent-folder       . "/Lissner.net/Sent Mail")
-(set! :email "lissner.net"
+      (mu4e-drafts-folder     . "/Lissner.net/Drafts")
-    '((mu4e-sent-folder       . "/%s/Sent Mail")
+      (mu4e-trash-folder      . "/Lissner.net/Trash")
-      (mu4e-drafts-folder     . "/%s/Drafts")
+      (mu4e-refile-folder     . "/Lissner.net/All Mail")
-      (mu4e-trash-folder      . "/%s/Trash")
-      (mu4e-refile-folder     . "/%s/All Mail")
       (smtpmail-smtp-user     . "henrik@lissner.net")
       (user-mail-address      . "henrik@lissner.net")
       (mu4e-compose-signature . "---\nHenrik Lissner"))

modules/app/irc/README.org

@@ -1,11 +1,17 @@
-* :app irc
+#+TITLE: :app irc
 
 This module turns adds an IRC client to Emacs ([[https://github.com/jorgenschaefer/circe][~circe~)]] with native notifications ([[https://github.com/eqyiel/circe-notifications][circe-notifications]]).
 
-** Dependencies
+* Table of Contents :TOC:
+- [[#dependencies][Dependencies]]
+- [[#configure][Configure]]
+  - [[#pass-the-unix-password-manager][Pass: the unix password manager]]
+  - [[#emacs-auth-source-api][Emacs' auth-source API]]
+
+* Dependencies
 This module has no dependencies, besides =gnutls-cli= or =openssl= for secure connections.
 
-** Configure
+* Configure
 Use the ~:irc~ setting to configure IRC servers. Its second argument (a plist) takes the same arguments as ~circe-network-options~.
 
 #+BEGIN_SRC emacs-lisp :tangle no
@@ -19,7 +25,7 @@ Use the ~:irc~ setting to configure IRC servers. Its second argument (a plist) t
 
 *It is a obviously a bad idea to store auth-details in plaintext,* so here are some ways to avoid that:
 
-*** Pass: the unix password manager
+** Pass: the unix password manager
 [[https://www.passwordstore.org/][Pass]] is my tool of choice. I use it to manage my passwords. If you activate the [[/modules/tools/password-store/README.org][:tools password-store]] module you get an elisp API through which to access your password store.
 
 ~:irc~'s plist can use functions instead of strings. ~+pass-get-user~ and ~+pass-get-secret~ can help here:
@@ -46,7 +52,7 @@ But wait, there's more! This stores your password in a public variable which cou
 
 And you're good to go!
 
-*** Emacs' auth-source API
+** Emacs' auth-source API
 ~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store (and retrieve) encrypted passwords with it.
 
 #+BEGIN_SRC emacs-lisp :tangle no

modules/completion/company/README.org

@@ -1,29 +1,33 @@
-* :completion company
+#+TITLE: :completion company
 
-This module adds completion support powered by [[https://github.com/company-mode/company-mode][company]].
+This module adds code-completion support, powered by [[https://github.com/company-mode/company-mode][company]].
 
 + Uses ~company-quickhelp~ for documentation tooltips
 + Uses ~company-statistics~ to order results by usage frequency
 
 [[/../screenshots/company.png]]
 
-** Install
+* Table of Contents :TOC:
-Specific languages may require additional setup. Some languages may have no completion support at all.
+- [[#install][Install]]
+- [[#configure][Configure]]
+  - [[#auto-completion][Auto-completion]]
+- [[#troubleshooting][Troubleshooting]]
+
+* Install
+Certain languages may require additional setup, and some languages may have no completion support at all.
 
 Check the README.org in that language's module for details.
 
-** Customization
+* Configure
-This module is configured to suit my preferences. Here are some things you may want to change:
+** Auto-completion
+By default, I've disabled auto-completion. This is my preference. I prefer to invoke company when I need it by calling ~company-complete~ manually (typically, bound to =C-SPC= in insert mode). However, some may not share my preference.
 
-*** as-you-type completion
+To enable auto-completion you must:
-By default, I've disabled auto-completion. This is my preference. I prefer to invoke company when I need it by pressing ~C-SPC~ from insert mode. Some don't like this.
-
-To make it automatic, you need to do two things:
 
 1. Load ~company~,
 2. and change ~company-idle-delay~ to a non-nil float (the default is 0.5)
 
-To do this, add the following to your ~modules/private/<username>~ module (remember, ~:private <username>~ needs to be added to init.el):
+For example, add the following to your ~modules/private/<username>/config.el~ module:
 
 #+BEGIN_SRC emacs-lisp
 (require 'company)
@@ -31,9 +35,9 @@ To do this, add the following to your ~modules/private/<username>~ module (remem
       company-minimum-prefix-length 3)
 #+END_SRC
 
-** Troubleshooting
+* Troubleshooting
 If completion isn't working for you, please consider the following before posting a bug report:
 
-+ Different languages will have different dependencies in order for auto-completion to work. Please look for the README.org in that language's respective module for details.
++ If what you are expecting is popup-as-you-type completion (which is disabled by default), see the "Customize" section above; it includes instructions on how to enable this.
++ Certain languages may have extra dependencies in order for auto-completion to work. Please look for that module's README.org for details.
 + Some languages don't have any auto-completion support.
-+ Check [[*Customization][Customization]], perhaps what you are expecting is popup-as-you-type completion, which is disabled by default.

modules/completion/ivy/README.org

@@ -1,93 +1,96 @@
-* :completion ivy
+#+TITLE: :completion ivy
 
-This module adds the Ivy completion backend.
+This module adds Ivy, a completion backend.
 
-I prefer ivy over ido and helm, for its speed and simplicity. With ivy's help and some hackery, I get the following features:
+#+begin_quote
+I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter.
+#+end_quote
 
-+ Project-wide search & replace powered by ~rg~ and ~ag~
++ Project-wide search & replace powered by ~rg~ or ~ag~
 + Project jump-to navigation ala Command-T, Sublime Text's Jump-to-anywhere or Vim's CtrlP plugin.
 + Ivy integration for ~M-x~, ~imenu~, ~recentf~ and others.
 + A powerful, interactive in-buffer search using ~swiper~.
 + Ivy-powered TODO/FIXME navigation
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+  - [[#macos][MacOS]]
+  - [[#arch-linux][Arch Linux]]
+- [[#usage][Usage]]
+  - [[#project-search--replace][Project search & replace]]
+  - [[#jump-to-file-project-navigation][Jump-to-file project navigation]]
+  - [[#in-buffer-searching][In-buffer searching]]
+  - [[#task-lookup][Task lookup]]
+- [[#appendix][Appendix]]
+  - [[#commands][Commands]]
+  - [[#hacks][Hacks]]
+
+* Install
 This module optionally depends on [[https://github.com/BurntSushi/ripgrep][ripgrep]] and [[https://github.com/ggreer/the_silver_searcher][the_silver_searcher]].
 
-~rg~ is faster, but its results aren't deterministic and it doesn't support multiline search or full PCRE, that's where ~ag~ is useful.
+~rg~ is faster, but its results aren't deterministic, neither does it support multiline search or full PCRE, that's where ~ag~ is useful.
 
-*** MacOS
+** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew install ripgrep the_silver_searcher
 #+END_SRC
 
-*** Arch Linux
+** Arch Linux
 #+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
 sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher
 #+END_SRC
 
-** Usage
+* Usage
-*** Search & Replace
+Here is some insight into how I use this module. Keep in mind that the referenced commands and keybindings are defined [[/modules/private/hlissner][in my private module]].
-A project-wide search can be performed with Ag (the silver searcher) or Rg
+
-(ripgrep) via their ex commands: ~:ag[!]~ and ~:rg[!]~ (or their
+** Project search & replace
-current-directory counterparts ~:agcwd[!]~ and ~:rgcwd[!]~)
+Ex interfaces to Ag (the silver searcher) and Rg (ripgrep) are available: ~:ag[!]~ and ~:rg[!]~, or their current-directory counterparts ~:agcwd[!]~ and ~:rgcwd[!]~.
 
 [[/../screenshots/modules/completion/ivy/ivy-search.gif]]
 
-From this session, you can press =Shift + Tab= to create an writeable occur
+From this session, you can press =S+Tab= to create a writeable occur-buffer in wgrep mode.
-buffer in wgrep mode.
 
 [[/../screenshots/modules/completion/ivy/ivy-search-replace.gif]]
 
-Make your modifications and press =C-c C-c= to commit them, or =C-c C-k= to
+Make your modifications and press =C-c C-c= to commit them, or =C-c C-k= to abort.
-abort.
 
-*** Jump-to-file project navigation
+** Jump-to-file project navigation
-Inspired by Sublime Text's jump-to-anywhere, Vim's CtrlP or Unite plugins, and
+Inspired by Sublime Text's jump-to-anywhere, Vim's CtrlP or Unite plugins, and Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available to you in Emacs. Invoke it with =SPC f /=, =SPC SPC= or ~counsel-projectile-find-file~.
-Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available
-to you in Emacs. Invoke it with =<leader> /= or ~counsel-projectile-find-file~.
 
 [[/../screenshots/modules/completion/ivy/ivy-projectile.gif]]
 
-*** In-buffer searching
+** In-buffer searching
-I prefer to use ~evil-search~ (invoked by pressing =/= in normal mode) when
+I use ~evil-search~ (invoked by pressing =/= in normal mode) when jumping small/moderate (or predictable) distances. However, there are occasions where I need more feedback, so I turn to ~swiper~ (available directly with =M-x swiper RET=, or via ~:sw[iper]~).
-jumping small/moderate (or predictable) distances. On occasion I need more
-feedback, so I turn to ~swiper~ (available directly with =M-x swiper RET=, or
-via ~:sw[iper]~).
 
 [[/../screenshots/modules/completion/ivy/ivy-swiper.gif]]
 
-*** TODO-Task lookup
+** Task lookup
-I sprinkle my projects with TODO's & FIXME's. Using ivy and ripgrep, I wrote
+I sprinkle my projects with TODO's & FIXME's. You can navigate to and peruse them via ~M-x +ivy/tasks~ or ~:todo[!]~ (ex command).
-~+ivy/tasks~ to help me navigate to them. It can be invoked via ~:todo[!]~ as
-well.
 
 [[/../screenshots/modules/completion/ivy/ivy-todo.gif]]
 
-** Appendix
+* Appendix
-*** Commands & Keybindings
+** Commands
-Here is a list of my commonly used commands, their default keybinds (defined in
+Here is a list of my commonly used commands, their default keybinds (defined in [[../../private/hlissner/+bindings.el][private/hlissner/+bindings.el]]), and their corresponding ex command (defined in [[../../private/hlissner/+commands.el][private/hlissner/+commands.el]]).
-[[../../private/hlissner/+bindings.el][private/hlissner/+bindings.el]]), and their corresponding ex command (defined in
-[[../../private/hlissner/+commands.el][private/hlissner/+commands.el]]).
 
-| command                             | key / ex command    | description                                                      |
+| command                             | key / ex command       | description                                                      |
-|-------------------------------------+---------------------+------------------------------------------------------------------|
+|-------------------------------------+------------------------+------------------------------------------------------------------|
-| ~counsel-M-x~                       | =M-x=               | Smarter, smex-powered M-x                                        |
+| ~counsel-M-x~                       | =M-x=                  | Smarter, smex-powered M-x                                        |
-| ~counsel-bookmark~                  | =<leader> b=        | Find bookmark                                                    |
+| ~counsel-bookmark~                  | =SPC RET=              | Find bookmark                                                    |
-| ~counsel-find-file~                 | =<leader> .=        | Browse from current directory                                    |
+| ~counsel-find-file~                 | =SPC f .= or =SPC .=   | Browse from current directory                                    |
-| ~counsel-projectile-find-file~      | =<leader> /=        | Find file in project                                             |
+| ~counsel-projectile-find-file~      | =SPC f /= or =SPC SPC= | Find file in project                                             |
-| ~counsel-projectile-switch-project~ | =<leader> p=        | Open another project                                             |
+| ~counsel-projectile-switch-project~ | =SPC p p=              | Open another project                                             |
-| ~counsel-recentf~                   | =<leader> r=        | Find recently opened file                                        |
+| ~counsel-recentf~                   | =SPC f r=              | Find recently opened file                                        |
-| ~+ivy/switch-buffer~                | =<leader> ,=        | Jump to buffer in current workspace                              |
+| ~ivy-switch-buffer~                 | =SPC b b=              | Jump to buffer in current workspace                              |
-| ~+ivy/switch-workspace-buffer~      | =<leader> <=        | Jump to buffer across workspaces                                 |
+| ~+ivy/switch-workspace-buffer~      | =SPC b B=              | Jump to buffer across workspaces                                 |
-| ~+ivy:ag~                           | ~:ag[!] [QUERY]~    | Search project (BANG = ignore gitignore)                         |
+| ~+ivy:ag~                           | ~:ag[!] [QUERY]~       | Search project (BANG = ignore gitignore)                         |
-| ~+ivy:ag-cwd~                       | ~:agcwd[!] [QUERY]~ | Search this directory (BANG = don't recurse into subdirectories) |
+| ~+ivy:ag-cwd~                       | ~:agcwd[!] [QUERY]~    | Search this directory (BANG = don't recurse into subdirectories) |
-| ~+ivy:rg~                           | ~:rg[!] [QUERY]~    | Search project (if BANG, ignore gitignore)                       |
+| ~+ivy:rg~                           | ~:rg[!] [QUERY]~       | Search project (if BANG, ignore gitignore)                       |
-| ~+ivy:rg-cwd~                       | ~:rgcwd[!] [QUERY]~ | Search this directory (BANG = don't recurse into subdirectories) |
+| ~+ivy:rg-cwd~                       | ~:rgcwd[!] [QUERY]~    | Search this directory (BANG = don't recurse into subdirectories) |
-| ~+ivy:swiper~                       | ~:sw[iper] [QUERY]~ | Search current buffer                                            |
+| ~+ivy:swiper~                       | ~:sw[iper] [QUERY]~    | Search current buffer                                            |
-| ~+ivy:todo~                         | ~:todo[!]~          | List all TODO/FIXMEs in project (or current file if BANG)        |
+| ~+ivy:todo~                         | ~:todo[!]~             | List all TODO/FIXMEs in project (or current file if BANG)        |
 
-While in a search (e.g. invoked from ~+ivy:ag~ or ~+ivy:rg~), these new
+While in a search (e.g. invoked from ~+ivy:ag~ or ~+ivy:rg~), these new keybindings are available to you:
-keybindings are available to you:
 
 | key         | description                                                                    |
 |-------------+--------------------------------------------------------------------------------|
@@ -95,10 +98,8 @@ keybindings are available to you:
 | =C-SPC=     | Preview the current candidate                                                  |
 | =M-RET=     | Open the selected candidate in other-window                                    |
 
-*** Hacks
+** Hacks
-+ Where possible, functions with ivy/counsel equivalents have been remapped
++ Functions with ivy/counsel equivalents have been globally remapped (like ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will invoke ~counsel-find-file~ instead.
-  (like ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will
-  invoke ~counsel-find-file~ instead.
 + ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex command)
 + ~counsel-[arp]g~'s parentheses quoting behavior was reversed. Now, if you
   want literal parentheses, you must escape them: e.g. ~\(match\)~ is literal,

modules/feature/eval/README.org

@@ -1,17 +1,21 @@
-* :feature eval
+#+TITLE: :feature eval
 
-This module adds support for:
+This modules adds support for REPLs, build tasks and code evaluation.
 
-+ [[#repls][Defining, invoking & interacting with REPLs]],
+* Table of Contents :TOC:
-+ [[#build-tasks][Defining & invoking build tasks for projects and files]],
+- [[#install][Install]]
-+ and [[#code-evaluation][evaluating code or entire buffers, printing their output to a popup window]].
+- [[#usage][Usage]]
+- [[#configuration][Configuration]]
+  - [[#repls][REPLs]]
+  - [[#build-tasks][Build Tasks]]
+  - [[#code-evaluation][Code Evaluation]]
 
-** Install
+* Install
 This module has no external dependencies. However, specific languages may require additional setup.
 
 Check the README.org in that language's module for details.
 
-** Usage
+* Usage
 + *REPLs*
   Invoked via:
   + ~:repl~ (evil ex-command)
@@ -33,13 +37,15 @@ Check the README.org in that language's module for details.
   + ~M-x +eval/region-and-replace~
   + Evil users can use the ~gr~ operator to select and run a region.
 
-** Configuration
+* Configuration
-*** REPLs
+** REPLs
-REPLs have been defined for most of the languages DOOM supports (check its README.org to see if it does).
+REPLs are defined for most of the languages Doom supports (check its README.org to see if it does).
 
-Otherwise, you can define your own:
+Otherwise, you can define your own for a specified major-mode with the =:repl= setting.
 
-A REPL definition consists of two parts: an interactive command that opens (and returns) a REPL buffer and a ~:repl~ definition that maps a major-mode to said command:
+~(set! :repl MAJOR-MODE FUNCTION)~
+
+FUNCTION must return the repl buffer. Any window changes are ignored, then handed off to shackle (assuming shackle-mode is on) to display in a popup window.
 
 #+BEGIN_SRC emacs-lisp
 (defun +emacs-lisp/repl ()
@@ -54,8 +60,8 @@ A REPL definition consists of two parts: an interactive command that opens (and
 (set! :repl 'emacs-lisp-mode #'+emacs-lisp/repl)
 #+END_SRC
 
-*** Build Tasks
+** Build Tasks
-A build task is little more than major-mode-local commands, comprised of an interactive command, an association with a major mode and an optional predicate function.
+A build task is little more than a major-mode-local interactive command that performs a task, such as compiling the current project or running unit tests. A predicate function can be supplied to ensure a command is only available when it is appropriate.
 
 #+BEGIN_SRC emacs-lisp
 (defun +lua/run-love ()
@@ -83,7 +89,7 @@ A build task is little more than major-mode-local commands, comprised of an inte
 (set! :build 'generate-docs 'lua-mode #'+lua/generate-docs)
 #+END_SRC
 
-*** Code Evaluation
+** Code Evaluation
 Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output will be sent to a popup window.
 
 Quickrun includes support for many languages, but occasionally, you'll find a language without support, such as [[https://crystal-lang.org/][Crystal]]. A "runner" can be defined like so:

modules/feature/evil/README.org

@@ -1,20 +1,27 @@
-* :feature evil
+#+TITLE: :feature evil
 
-This holy module brings vim to Emacs.
+This holy module brings the vim experience to Emacs.
 
-** Removing evil-mode
+* Table of Contents :TOC:
-Some users want vanilla Emacs back. To do so remove =:feature evil= from init.el. Evil-specific configuration and keybindings (defined with ~map!~) will be ignored without evil present (and removed when byte-compiling).
+- [[#removing-evil-mode][Removing evil-mode]]
+- [[#features][Features]]
+  - [[#multiple-cursors][Multiple-cursors]]
+  - [[#a-hybrid-code-folding-system][A hybrid code-folding system]]
+  - [[#hacks][Hacks]]
+  - [[#differences-from-vim][Differences from vim]]
 
-** Differences from vanilla evil
+* Removing evil-mode
-*** Overview
+To get back a more vanilla Emacs experience, remove =:feature evil= from init.el. Evil-specific configuration and keybindings (defined with ~map!~) will be ignored without evil present (and removed when byte-compiling).
-+ A better ~:g[lobal]~ command with match highlighting
+
-+ ~:al[ign]~: an ex interface to ~align-regexp~ with match highlighting
+* Features
++ A better ~:g[lobal]~ command with incremental highlighting.
++ Adds the ~:al[ign]~ ex command: offers an ex interface to ~align-regexp~ with incremental highlighting.
 + Support for more of vim's filename modifiers in ex commands (like ~:p~, ~:p:h~ or ~:t~) than vanilla evil-mode offers.
 + A list of new text objects:
   + Blocks: ~B~ (from ~evil-textobj-anyblock~)
   + Args: ~a~ (from ~evil-args~)
   + Indentation: ~i~ / ~I~ / ~J~ (from ~evil-indent-plus~)
-+ Ported vim plugins:
++ Incorporates vim functionality ported to evil:
   + ~vim-commentary~ => ~evil-commentary~
   + ~vim-easymotion~ => ~evil-easymotion~
   + ~vim-multiedit~ => ~evil-multiedit~
@@ -23,19 +30,21 @@ Some users want vanilla Emacs back. To do so remove =:feature evil= from init.el
   + ~vim-surround~ => ~evil-embrace~ & ~evil-surround~
 + =NERDTree= equivalent is available in =:tools neotree=
 
-*** Multiple-cursors
+** Multiple-cursors
 Two multiple-cursor implementations exist in this module: ~evil-mc~ and ~evil-multiedit~. Together, these provide the functionality of ~vim-multiple-cursors~.
 
 The former lets you place "clone" cursors. The latter lets you interactively edit many regions from one place (like an interactive version of ~:%s~).
 
-*** A saner code-folding system
+** A hybrid code-folding system
-This module combines ~evil-vimish-fold~ (allows arbitrary folds) and ~hideshow~ (folds based on markers and indent) to create a more consistent code-folding system. All the vim folding keys should work (=zr=, =zm=, =za=, =zo=, etc).
+This module combines ~evil-vimish-fold~ and ~hideshow~. The former allows arbitrary folds and the latter allows folds on markers and indentation. Together, they create a more consistent (and feature-complete) code-folding system.
 
-*** Hacks
+Most vim folding keys should work, e.g. =zr=, =zm=, =za=, =zo=, etc.
+
+** Hacks
 + Automatically moves to new window when splitting
 + If in visual mode, =*= and =#= will search for the current selection instead of the word-at-point.
 
 ** Differences from vim
 + Column-wise ranges in ex commands are enabled by default. i.e. the range in =:'<,'>s/a/b= will only affects the visual selection, not full lines (see ~evil-ex-visual-char-range~).
-+ =:g= will highlight buffer matches incrementally.
++ =:g= will incrementally highlight buffer matches.
 

modules/lang/cc/README.org

@@ -1,4 +1,4 @@
-* :lang cc
+#+TITLE: :lang cc
 
 This module adds support for the C-family of languages: C, C++, and Objective-C.
 
@@ -8,17 +8,23 @@ This module adds support for the C-family of languages: C, C++, and Objective-C.
 + Code navigation (~irony~)
 + File Templates ([[../../feature/file-templates/templates/c-mode][c-mode]], [[../../feature/file-templates/templates/c++-mode][c++-mode]])
 + Snippets ([[https://github.com/hlissner/emacs-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/emacs-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/emacs-snippets/tree/master/c++-mode][c++-mode]])
++ Several improvements to C++11 indentation and syntax highlighting.
 
 #+begin_quote
-C contends with Haskell and Ruby for my favorite language. It's hard to beat this combination of simplicity and power. I've used C for my work since 2009, and it (along with C++) is a personal favorite for game development (with SDL, SFML or, more recently, cocos2d).
+C contends with Haskell and Ruby for my favorite language. That said, it's more accurate to say I write C, but with two or three C++ features.
 
 The module provides nominal support for Objective-C, which I really only use to inspect generated glue code for iOS mobile apps. Otherwise, I prefer Swift.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+  - [[#macos][MacOS]]
+  - [[#arch-linux][Arch Linux]]
+
+* Install
 This module requires ~irony-server~ for most of its features, which depends on ~cmake~ and ~libclang~.
 
-*** MacOS
+** MacOS
 Due to linking issues, MacOS users must compile irony-server manually:
 
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
@@ -43,9 +49,10 @@ popd
 rm -rf irony-mode
 #+END_SRC
 
-*** Arch Linux
+** Arch Linux
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'arch) "yes")
 sudo pacman --needed --noconfirm -S clang cmake
 #+END_SRC
 
 Then run ~M-x irony-install-server~ in Emacs.
+

modules/lang/go/README.org

@@ -1,4 +1,4 @@
-* :lang go
+#+TITLE: :lang go
 
 This module adds [[https://golang.org][Go]] support.
 
@@ -13,12 +13,18 @@ This module adds [[https://golang.org][Go]] support.
 + [[https://github.com/hlissner/emacs-snippets/tree/master/go-mode][Snippets]]
 
 #+begin_quote
-I have mixed feelings about Go. It's a decent compromise between C and higher-level languages. It's a pleasantly straight-forward language with elegant syntax, but it lacks /native/ support for certain luxuries I miss from other languages, like generics, optional arguments, and function overloading. You've got to learn to love ~interface{}~.
+I have mixed feelings about Go. It's a decent compromise between C and higher-level languages, is pleasantly straight-forward and elegant, but lacks /native/ support for luxuries I miss from other languages, like generics, optional arguments, and function overloading. You've got to learn to love ~interface{}~.
 
 Still, Go has been a remarkably useful (and fast!) companion for a variety of small-to-medium backend web and CLI projects.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+  - [[#go][Go]]
+  - [[#dependencies][Dependencies]]
+
+* Install
+** Go
 To get started with Go, you need the ~go~ tool:
 
 *** MacOS

modules/lang/haskell/README.org

@@ -1,4 +1,4 @@
-* :lang haskell
+#+TITLE: :lang haskell
 
 This module adds [[https://www.haskell.org/][Haskell]] support.
 
@@ -11,52 +11,55 @@ This module adds [[https://www.haskell.org/][Haskell]] support.
 + [[https://github.com/hlissner/emacs-snippets/tree/master/haskell-mode][Snippets]]
 
 #+begin_quote
-Haskell contends with C and Ruby as my favorite language. I don't think my Haskell code will ever save the world, but I'll reach for it when working on smaller projects and programming exercises (like projecteuler.com or exercism.io).
+Haskell contends with C and Ruby as my favorite language. I don't think my Haskell code will ever save the world, but I'll reach for it for small projects and programming exercises (like projecteuler.com or exercism.io).
 
 I'd love to incorporate more of it into my machine learning work, but Python and Julia hold that crown. For now.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
-To get started with Haskell, you need:
+- [[#install][Install]]
+  - [[#haskell][Haskell]]
+  - [[#dependencies][Dependencies]]
+- [[#troubleshooting][Troubleshooting]]
+- [[#resources][Resources]]
 
-+ cabal (the haskell package builder)
+* Install
-+ ghc/ghci (the compiler, syntax checker & repl)
+** Haskell
+To get started with Haskell, you need *stack* installed.
 
 *** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
-brew install cabal-install ghc
+brew install haskell-stack
+stack setup
 #+END_SRC
 
 *** Arch Linux
 #+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
-sudo pacman --needed --noconfirm -S cabal-install ghc
+sudo pacman --needed --noconfirm -S stack
+# Replace pacaur with your AUR package manager of choice
+pacaur --needed --noconfirm -S ncurses5-compat-lib
+stack setup
 #+END_SRC
 
 ** Dependencies
-This module requires the following ~cabal~ packages:
+This module requires ~ghc-mod~ (as well as ~intero~, but those will be automatically installed).
-
-+ ~happy~ (required by ~haskell-src-exts~)
-+ ~haskell-src-exts~ (required by ~ghc-mod~ & ~hoogle~)
-+ ~ghc-mod~ (for auto-completion)
-+ ~hoogle~ (for documentation lookup)
 
 #+BEGIN_SRC sh
-cabal update
+stack install ghc-mod
-cabal install happy haskell-src-exts ghc-mod hoogle
 #+END_SRC
 
-Ensure that ~\~/.cabal/bin~ is in ~PATH~:
+Also ensure that ~\~/.local/bin~ is in ~PATH~:
 
 #+BEGIN_SRC sh
 # place this in your profile file, like ~/.bash_profile or ~/.zshenv
-export PATH="~/.cabal/bin:$PATH"
+export PATH="~/.local/bin:$PATH"
 #+END_SRC
 
-** Troubleshooting
+* Troubleshooting
 + Stack users: if a ~dist/setup-config~ file exists in your project, [[ https://github.com/DanielG/ghc-mod/wiki#known-issues-related-to-stack][ghc-mod may
   refuse to work]].
 
-** Resources
+* Resources
 Here are a few resources I've found indespensible in my Haskell adventures:
 
 + [[http://learnyouahaskell.com/][Learn you a haskell for great good]]

modules/lang/php/README.org

@@ -1,4 +1,4 @@
-* :lang php
+#+TITLE: :lang php
 
 This module adds support for PHP 5.3+ (including PHP7).
 
@@ -12,14 +12,18 @@ This module adds support for PHP 5.3+ (including PHP7).
 + [[https://github.com/hlissner/emacs-snippets/tree/master/php-mode][Snippets]]
 
 #+begin_quote
-PHP was the first programming language I got paid to code in, back in the Cretaceous period (2003). I'm so, so sorry. All those programmers who inherited my earliest PHP work. I know you're out there, writhing in your straitjackets.
+PHP was the first programming language I got paid to code in, back in the Cretaceous period (2003). My sincerest apologies go out to all the programmers who inherited my earliest PHP work. I know you're out there, writhing in your straitjackets.
-
-I suppose it's hip for programmers to projectile vomit to any mention of PHP, but they have good reason to. Not because it's /necessarily/ a bad language, and not /just/ because of a couple inconsistently ordered parameters, but because it's too easy to make junk with. You've heard the war stories.
 
 Save a programmer today. Stop a friend from choosing PHP as their first language.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+  - [[#php][PHP]]
+  - [[#dependencies][Dependencies]]
+
+* Install
+** PHP
 To get started with PHP, you'll need ~php~ (5.3+) and ~composer~:
 
 *** MacOS
@@ -37,7 +41,7 @@ sudo pacman --needed --noconfirm -S php composer  # or php53, php54, php55
 #+END_SRC
 
 ** Dependencies
-The features in this module optionally depends on the following php packages:
+The features in this module optionally depend on the following php packages:
 
 + ~boris~ (REPL)
 + ~phpctags~ (better code completion)

modules/lang/rest/README.org

@@ -1,4 +1,4 @@
-* :lang rest
+#+TITLE: :lang rest
 
 This module adds [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] support.
 
@@ -10,10 +10,14 @@ This module adds [[https://en.wikipedia.org/wiki/Representational_state_transfer
 ~restclient-mode~ is tremendously useful for testing REST APIs. My workflow is to open an ~org-mode~ buffer, create a restclient source block and hack away. ~restclient-mode~ and ~company-restclient~ power this arcane wizardry.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#example][Example]]
+
+* Install
 No additional setup required.
 
-** Example
+* Example
 #+BEGIN_SRC restclient
 GET https://jsonplaceholder.typicode.com/posts/1
 #+END_SRC

modules/tools/neotree/README.org

@@ -1,4 +1,4 @@
-* :evil neotree
+#+TITLE: :evil neotree
 
 This module brings a side panel for browsing project files, inspired by vim's NERDTree.
 

modules/ui/doom-modeline/README.org

@@ -1,4 +1,4 @@
-* :ui doom-modeline
+#+TITLE: :ui doom-modeline
 
 This module customizes the Emacs mode-line.
 
@@ -17,12 +17,18 @@ The DOOM modeline was designed for minimalism, and offers:
 [[/../screenshots/ml-version.png]]
 [[/../screenshots/ml-errors.png]]
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#extracting-my-modeline][Extracting my modeline]]
+- [[#troubleshooting][Troubleshooting]]
+  - [[#where-are-my-minor-modes][Where are my minor modes?]]
+
+* Install
 This module requires the fonts included with ~all-the-icons~ to be installed.
 
 Run ~M-x all-the-icons-install-fonts~ to do so.
 
-** Extracting my modeline
+* Extracting my modeline
 Some might want my modeline without the DOOM config altogether. I've tried to make this easier for you, but there are a few things you'll need to do:
 
 + Ensure [[https://github.com/bbatsov/projectile][projectile]] and [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] are installed.
@@ -30,7 +36,6 @@ Some might want my modeline without the DOOM config altogether. I've tried to ma
 + Ensure the fonts included with ~all-the-icons~ are installed (~M-x all-the-icons-install-fonts~).
 + Replace ~def-package!~ calls with ~use-package~.
 + Replace ~doom-project-root~ calls with ~projectile-project-root~.
-+ Change the one ~def-memoized!~ function to ~defun~.
 + The ~+doom-modeline--make-xpm~ function is memoized with the ~def-memoized!~ macro. Change ~def-memoized!~ to ~defun~.
 + Copy the ~add-hook!~ macro definition from [[/master/core/core-lib.el][core/core-lib.el]].
 + Copy the following macros and functions from [[/master/core/core-ui.el][core/core-ui.el]]:
@@ -40,8 +45,8 @@ Some might want my modeline without the DOOM config altogether. I've tried to ma
   + ~doom-modeline~
   + ~doom-set-modeline~
 
-That /should/ be everything. As I have never used this out of my config I can't guarantee immediate success, but I'd be happy to help you out. File an issue.
+That /should/ be everything. As I have never used this out of my config I can't guarantee immediate success, but I'd be happy to help you out if you file an issue.
 
-** Troubleshooting
+* Troubleshooting
-*** Where are my minor-modes?
+** Where are my minor modes?
-I didn't need it, so I removed it. I wrote ~doom/what-minor-mode~ in the rare case I needed to investigate the currently active minor modes however.
+I didn't need it, so I removed it. Run ~M-x doom/what-minor-mode~ to investigate what minor modes are currently active.

modules/ui/doom/README.org

@@ -1,32 +1,60 @@
-* :ui doom
+#+TITLE: :ui doom
 
 This module modifies Emacs' user interface.
 
-DOOM's look is loosely inspired by Atom's One Dark theme, and is largely contained in the [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]] plugin.
+Doom's look is loosely inspired by Atom's One Dark theme, and is largely contained in the] plugin.
 
-By default, this module uses:
++ A colorscheme inspired by Atom's One Dark theme (now available in a separate plugin: [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]])
++ Uses the [[https://github.com/mozilla/Fira][Fira Mono and Fira Sans]] fonts, and [[https://dejavu-fonts.github.io/][DejaVu Sans Mono]] for unicode symbols.
++ A custom folded-region indicator for ~hideshow~
++ "Thin bar" fringe bitmaps for ~git-gutter-fringe~
++ File-visiting buffers are slightly brighter (powered by solaire-mode)
 
-+ [[https://github.com/mozilla/Fira][Fira Mono and Fira Sans]] (fonts)
+* Table of Contents :TOC:
-+ [[https://dejavu-fonts.github.io/][DejaVu Sans Mono]] (font, for displaying unicode characters)
+- [[#install][Install]]
-+ ~hideshow~, modified to use a nicer folded-region indicator.
+  - [[#macos][MacOS]]
-+ Custom fringe bitmaps for ~git-gutter-fringe~ (thin bars)
+  - [[#arch-linux][Arch Linux]]
+- [[#configuration][Configuration]]
+  - [[#changing-fonts][Changing fonts]]
+- [[#troubleshooting][Troubleshooting]]
+  - [[#strange-font-symbols][Strange font symbols]]
 
-** Install
+* Install
-[[https://github.com/mozilla/Fira][Fira Mono]] is this module's only dependency (if you want to use it).
+This module optionally depends on:
 
-*** MacOS
++ The [[https://github.com/mozilla/Fira][Fira Mono]] family of fonts
++ [[https://dejavu-fonts.github.io/][DejaVu Sans Mono]]
+
+You don't have to install these if you use a different font.
+
+** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew tap caskroom/fonts
 brew cask install font-fira-{sans,mono} font-dejavu-sans
 #+END_SRC
 
-*** Arch Linux
+** Arch Linux
 #+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
 sudo pacman --noconfirm --needed -S ttf-fira-{sans,mono} ttf-dejavu
 #+END_SRC
 
-** Troubleshooting
+* Configuration
-*** Strange font symbols
+** Changing fonts
-If you're getting strange unicode symbols, that is likely ~all-the-icons~ doing (caused by other UI modules, specifically [[../doom-modeline][doom-modeline]] and [[../doom-dashboard][doom-dashboard]]).
+There are four font settings you can change:
 
-You must install the fonts included with ~all-the-icons~ with: ~M-x all-the-icons-install-fonts~.
++ ~:font~ :: the default font.
++ ~:big-font~ :: the font to use when ~doom-big-font-mode~ is enabled.
++ ~:variable-font~ :: the font to use when ~variable-pitch-mode~ is active (or where the ~variable-pitch~ face is used).
++ ~:unicode-font~ :: the font used to display unicode symbols. This is ignored if the =:ui unicode= module is enabled.
+
+#+BEGIN_SRC emacs-lisp
+;; These are the defaults of this module
+(set! :font "Fira Mono" :size 12)
+(set! :big-font "Fira Mono" :size 18)
+(set! :variable-font "Fira Sans" :size 12)
+(set! :unicode-font "DejaVu Sans Mono" :size 12)
+#+END_SRC
+
+* Troubleshooting
+** Strange font symbols
+If you're seeing strange unicode symbols, this is likely because you don't have ~all-the-icons~'s font icon installed. You can install them with ~M-x all-the-icons-install-fonts~.

modules/ui/evil-goggles/README.org

@@ -1,12 +1,16 @@
-* :ui evil-goggles
+#+TITLE: :ui evil-goggles
 
 This module uses ~evil goggles~ to displays visual hints when editing with evil.
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#configure][Configure]]
+
+* Install
 This module requires:
 
 + ~evil~ (inherently tied to evil mode)
 
-** Configure
+* Configure
 By default, ~evil-goggles~ will be enabled by default and requires no additional configuration.
 

modules/ui/nav-flash/README.org

@@ -1,4 +1,4 @@
-* :ui nav-flash
+#+TITLE: :ui nav-flash
 
 This module uses ~nav-flash~ to flash the line around the cursor after any motion command that might reasonably send the cursor somewhere the eyes can't follow.
 
@@ -6,10 +6,14 @@ This module uses ~nav-flash~ to flash the line around the cursor after any motio
 Tremendously helpful on a 30" 2560x1600 display.
 #+end_quote
 
-** Install
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#configure][Configure]]
+
+* Install
 This module has no other dependencies.
 
-** Configure
+* Configure
 By default, ~nav-flash~ will be triggered whenever ~recenter~ is called. =:feature jump= attaches ~recenter~ to various hooks:
 
 #+BEGIN_SRC emacs-lisp