Update READMEs & add new ones

README.md

@@ -26,23 +26,45 @@ git clone https://github.com/hlissner/.emacs.d ~/.emacs.d
 cd ~/.emacs.d
 cp init.example.el init.el  # maybe edit init.el
 make install
-make compile       # optional, may take a while
-make compile-lite  # optional (lighter alternative to compile)
 
-# If you have problems, run this to diagnose any common problems
+# DOOM is designed to benefit from byte compilation, it can boost startup time
+# and make Emacs feel a bit snappier, but it is OPTIONAL.
+make compile       # may take a while
+# or
+make compile-lite  # lighter alternative to compile
+
+# If you have problems, run this to check for common issues with your setup
 make doctor
 ```
 
-If you change `init.el` or add/remove functions to autoload files, run `make`.
+If you byte-compile, changes to the config will **not** take effect until you
-That is the equivalent of running:
+recompile or delete the byte-compiled files (with `make clean`).
+
+## Package Management
+
+Plugins can be managed from the command line with `make`:
 
 ```bash
-make install       # or (doom/packages-install)
+make install     # install missing plugins
-make autoloads     # or (doom/reload-autoloads)
+make update      # update installed plugins
+make autoremove  # remove unused plugins
+# be sure to run install and autoremove after modifying init.el
+
+# run this if you change autoload files
+make autoloads
+
+# you can run any make command with DEBUG=1 for extra logging, and YES=1 to
+# auto-accept confirmation prompts:
+DEBUG=1 make install
+YES=1 make update
 ```
 
-You can run any Make command with `DEBUG=1` for added logging verbosity, and
+These can also be invoked from within emacs:
-`YES=1` to auto-accept any confirmation prompts.
+
++ `doom/packages-install`
++ `doom/packages-update`
++ `doom/packages-autoremove`
++ `doom/reload-autoloads`
 
 ## Deciphering my emacs.d
 
@@ -83,8 +105,8 @@ So you want to grok some of this madness. Here are a few suggestions:
     (see `:ag` and `:rg`)
   * Project search & replace with **[wgrep]**
   * Interactive buffer search with **[swiper]**
-* REPLs & inline/live code evaluation (using **[quickrun]**) with languages
+* Inline/live code evaluation (using **[quickrun]**) and REPLs for a variety of
-  support for Ruby, Python, PHP, JS, Elisp, Haskell, Lua and more.
+  languages, including Ruby, Python, PHP, JS, Elisp, Haskell, Lua and more.
 * [Minimalistic diffs in the fringe][sc-diffs] with **[git-gutter-fringe]**.
 * A do-what-I-mean jump-to-definition implementation that tries its darnest to
   find the definition of what you're looking at. It tries major-mode commands,
@@ -102,13 +124,24 @@ So you want to grok some of this madness. Here are a few suggestions:
   * RSS feed reader (using elfeed)
   * Word Processor (using LaTeX, Org and Markdown)
 
-## Contributing or troubleshooting
+## Troubleshooting
 
 My config wasn't intended for public use, but I'm happy to help you use or crib
-from my config. I welcome contributions of any kind; documentation, bug
+from my config.
-fixes/reports, even elisp tips.
 
-[Don't hesitate to tell me my Elisp-fu sucks](https://github.com/hlissner/.emacs.d/issues/new)!
++ If you have questions, drop me line at henrik@lissner.net.
++ If you have issues running or setting up my Emacs config, use `make doctor` to
+  help diagnose the issue before you report an issue.
++ If you still can't make sense of it, run `DEBUG=1 make doctor` and include
+  it [with your bug report][new-issue].
+
+**And please include steps to reproduce your issue, if possible**.
+
+## Contributing
+
+I welcome contributions of any kind; documentation, bug fixes/reports, extra
+modules, even elisp tips. Really,
+[don't hesitate to tell me my Elisp-fu sucks][new-issue]!
 
 
 [ag]: https://github.com/ggreer/the_silver_searcher
@@ -124,6 +157,7 @@ fixes/reports, even elisp tips.
 [git-gutter-fringe]: https://melpa.org/#/git-gutter-fringe
 [ivy]: https://melpa.org/#/ivy
 [neotree]: https://melpa.org/#/neotree
+[new-issue]: https://github.com/hlissner/.emacs.d/issues/new
 [persp-mode]: https://melpa.org/#/persp-mode
 [quickrun]: https://melpa.org/#/quickrun
 [rg]: https://github.com/BurntSushi/ripgrep

TODO.org

@@ -5,7 +5,7 @@
 + [-] Work-in-progress
 + [X] Complete
 
-** Planned [6/76]
+** Planned [11/76]
 + [0/14] Potential plugins
   + [ ] completion/ivy: [[https://github.com/yevgnen/ivy-rich][ivy-rich]], possible replacement for my ivy-buffer modifications (undecided)
   + [ ] app/present: [[https://github.com/larstvei/Focus][focus]], for presenting code
@@ -26,7 +26,7 @@
   + [ ] app/irc
   + [-] app/crm
   + [-] app/write
-+ [6/58] Add README.org's (with working babel blocks?) to modules (see [[modules/lang/go/README.org][lang/go/README.org]]) to replace bootstaps
++ [11/58] Add README.org's (with working babel blocks?) to modules (see [[modules/lang/go/README.org][lang/go/README.org]]) to replace bootstaps
   + [0/9] :tools
     + [ ] dired
     + [ ] electric-indent
@@ -37,7 +37,7 @@
     + [ ] term
     + [ ] tmux
     + [ ] upload
-  + [3/25] :lang
+  + [5/25] :lang
     + [ ] assembly
     + [X] cc
     + [ ] crystal
@@ -45,7 +45,7 @@
     + [ ] data
     + [ ] emacs-lisp
     + [X] go
-    + [ ] haskell
+    + [X] haskell
     + [ ] java
     + [ ] javascript
     + [ ] julia
@@ -53,7 +53,7 @@
     + [ ] lua
     + [ ] markdown
     + [ ] org
-    + [ ] php
+    + [X] php
     + [ ] python
     + [X] rest
     + [ ] ruby
@@ -63,9 +63,9 @@
     + [ ] swift
     + [ ] typescript
     + [ ] web
-  + [0/10] :feature
+  + [1/10] :feature
     + [ ] debug
-    + [ ] eval
+    + [X] eval
     + [ ] evil
     + [ ] file-templates
     + [ ] jump
@@ -74,15 +74,15 @@
     + [ ] syntax-checker
     + [ ] version-control
     + [ ] workspaces
-  + [1/5] :ui
+  + [2/5] :ui
     + [X] doom
     + [ ] doom-dashboard
-    + [ ] doom-modeline
+    + [X] doom-modeline
     + [ ] doom-quit
     + [ ] hl-todo
-  + [1/4] :completion
+  + [2/4] :completion
     + [X] ivy
-    + [ ] company
+    + [X] company
     + [ ] ido
     + [ ] helm
   + [1/5] :app

modules/app/email/README.org

@@ -1,18 +1,21 @@
-* Email
+* :app email
 
-I want to live in Emacs, but as we all know, living is incomplete without email.
+This module makes Emacs an email client, using ~mu4e~.
-So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing
-combined with org-mode for writing emails? Yes please.
-
-It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email
-via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand).
 
 #+begin_quote
-My config is gmail/gsuite oriented, and since Google has its own opinions on the
+I want to live in Emacs, but as we all know, living is incomplete without email. So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing combined with org-mode for writing emails? /Yes please./
-IMAP standard, it is unlikely to translate to other hosts.
+
+It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand).
+
+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
 
-** Installation
+** Install
+This module requires:
+
++ ~offlineimap~ (to sync mail with)
++ ~mu~ (to index your downloaded messages)
+
 *** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew install mu --with-emacs
@@ -24,11 +27,10 @@ brew install offlineimap
 sudo pacman --noconfirm --needed -S offlineimap mu
 #+END_SRC
 
-** Setup
+** Dependencies
-First, you need to set up, download and index your email:
+You need to do the following:
 
-1. Write a ~\~/.offlineimaprc~. Mine can be found [[https://github.com/hlissner/dotfiles/tree/master/shell/%252Bmu][in my dotfiles repository]]. It
+1. Write a ~\~/.offlineimaprc~. Mine can be found [[https://github.com/hlissner/dotfiles/tree/master/shell/%252Bmu][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I use unix pass to securely store my login credentials.
-   is configured to download mail to ~\~/.mail~.
 2. Download your email: ~offlineimap -o~ (may take a while)
 3. Index it with mu: ~mu index --maildir ~/.mail~
 
@@ -48,3 +50,4 @@ Then configure Emacs to use your email address:
       (mu4e-compose-signature . "---\nHenrik Lissner"))
     t)
 #+END_SRC
+

modules/completion/company/README.org

@@ -0,0 +1,39 @@
+* :completion company
+
+This module adds 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
+Specific languages may require additional setup. Some languages may have no completion support at all.
+
+Check the README.org in that language's module for details.
+
+** Customization
+This module is configured to suit my preferences. Here are some things you may want to change:
+
+*** as-you-type completion
+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):
+
+#+BEGIN_SRC emacs-lisp
+(require 'company)
+(setq company-idle-delay 0.2
+      company-minimum-prefix-length 3)
+#+END_SRC
+
+** 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.
++ 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,28 +1,31 @@
-* Ivy
+* :completion ivy
 
-Ivy is my completion backend of choice (over ido and helm), for its speed and
+This module adds the Ivy completion backend.
-simplicity. With ivy's help and some hackery, I get the following features:
 
-+ Project-wide search & replace.
+I prefer ivy over ido and helm, for its speed and simplicity. With ivy's help and some hackery, I get the following features:
+
++ Project-wide search & replace powered by ~rg~ (falls back to ~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
 
-** Dependencies
+** Install
-This module depends only on [[https://github.com/BurntSushi/ripgrep][ripgrep]].
+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.
 
 *** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
-brew install ripgrep
+brew install ripgrep the_silver_searcher
 #+END_SRC
 
 *** Arch Linux
 #+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
-sudo pacman --needed --noconfirm -S ripgrep
+sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher
 #+END_SRC
 
-** Highlights
+** Usage
 *** Search & Replace
 A project-wide search can be performed with Ag (the silver searcher) or Rg
 (ripgrep) via their ex commands: ~:ag[!]~ and ~:rg[!]~ (or their

modules/feature/eval/README.org

@@ -0,0 +1,109 @@
+* :feature eval
+
+This module adds support for:
+
++ [[#repls][Defining, invoking & interacting with REPLs]],
++ [[#build-tasks][Defining & invoking build tasks for projects and files]],
++ and [[#code-evaluation][evaluating code or entire buffers, printing their output to a popup window]].
+
+** 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
++ *REPLs*
+  Invoked via:
+  + ~:repl~ (evil ex-command)
+  + =<leader> o r= in normal mode (or visual mode, which sends the selection to the open REPL)
+  + ~M-x +eval/repl~
+  + ~M-x +eval/repl-send-region~ while a selection (and REPL) is active
+
++ *Build Tasks*
+  You will be prompted to select a task. Only the ones that meet the predicate will be listed.
+  + ~:build~ (evil ex-command)
+  + =M-b= (by default)
+  + =<leader> o b= in normal mode
+  + ~M-x +eval/build~
+
++ *Code Evaluation*
+  Quickrun can be invoked via:
+  + ~M-x +eval/buffer~ (or ~gR~, or ~M-r~)
+  + ~M-x +eval/region~
+  + ~M-x +eval/region-and-replace~
+  + Evil users can use the ~gr~ operator to select and run a region.
+
+** Configuration
+*** REPLs
+REPLs have been defined for most of the languages DOOM supports (check its README.org to see if it does).
+
+Otherwise, you can define your own:
+
+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:
+
+#+BEGIN_SRC emacs-lisp
+(defun +emacs-lisp/repl ()
+  (interactive)
+  (pop-to-buffer
+   (or (get-buffer "*ielm*")
+       (progn (ielm)
+              (let ((buf (get-buffer "*ielm*")))
+                (bury-buffer buf)
+                buf)))))
+
+(set! :repl 'emacs-lisp-mode #'+emacs-lisp/repl)
+#+END_SRC
+
+*** 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.
+
+#+BEGIN_SRC emacs-lisp
+(defun +lua/run-love ()
+  "Run the current project in love 10.0."
+  (async-shell-command
+   (format "/usr/bin/love %s"
+           (shell-quote-argument (doom-project-root)))))
+
+(defun +lua/build ()
+  "Run a build script in the project root."
+  (let ((default-directory (doom-project-root)))
+    (compile "luajit build.lua")))
+
+(defun +lua/generate-docs ()
+  "Generate project documentation."
+  (let ((default-directory (doom-project-root)))
+    (compile "luadoc *.lua")))
+
+(defun +lua-love-p ()
+  "Returns non-nil if the current project is a love project."
+  (doom-project-has! (and "main.lua" "config.lua")))
+
+(set! :build 'run           'lua-mode #'+lua/run-love :when (+lua-love-p))
+(set! :build 'build-project 'lua-mode #'+lua/build    :when (+lua-love-p))
+(set! :build 'generate-docs 'lua-mode #'+lua/generate-docs)
+#+END_SRC
+
+*** 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:
+
+#+BEGIN_SRC emacs-lisp
+(set! :eval 'crystal-mode
+      '((:command     . "crystal")
+        (:exec        . "%c %s")
+        (:description . "Run Crystal script")))
+#+END_SRC
+
+A simpler version is simply to use the path to the binary:
+
+#+BEGIN_SRC emacs-lisp
+(set! :eval 'groovy-mode "groovy")
+#+END_SRC
+
+Or if you'd rather run an elisp command:
+
+#+BEGIN_SRC emacs-lisp
+(set! :eval 'emacs-lisp-mode #'+emacs-lisp-eval)
+#+END_SRC
+

modules/lang/cc/README.org

@@ -1,29 +1,51 @@
-* C/C++/Obj-C
+* :lang cc
 
-I use C/C++ mostly for developing games. To that end, this module leverages the
+This module adds support for the C-family of languages: C, C++, and Objective-C.
-[[https://github.com/Sarcasm/irony-mode][irony plugin]] for auto-completion, eldoc documentation and syntax checking (with
-flycheck).
 
-Though it provides Objective-C support, I don't use it except to inspect
++ Code completion (~company-irony~)
-generated glue code for iOS mobile apps.
++ eldoc support (~irony-eldoc~)
++ Syntax-checking (~flycheck-irony~)
++ 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]])
 
-+ Snippets ([[https://github.com/hlissner/emacs-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/emacs-snippets/tree/master/c++-mode][c++-mode]])
+#+begin_quote
-+ File templates ([[../../feature/file-templates/templates/c-mode][c-mode]], [[../../feature/file-templates/templates/c++-mode][c++-mode]])
+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).
 
-** Installation
+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.
-~irony-server~ is required to use irony-mode's features auto-completion (among
+#+end_quote
-other things).
 
-To install it, run ~M-x irony-install-server~, which requires ~cmake~ and
+** Install
-~libclang~.
+This module requires ~irony-server~ for most of its features, which depends on ~cmake~ and ~libclang~.
 
 *** MacOS
+Due to linking issues, MacOS users must compile irony-server manually:
+
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew install cmake
-brew install llvm  # 1gb+ installer: may take a while!
+brew install llvm  # 1gb+ installation! May take a while!
+
+git clone https://github.com/Sarcasm/irony-mode irony-mode
+mkdir irony-mode/server/build
+pushd irony-mode/server/build
+
+DEST="$HOME/.emacs.d/.local/$(hostname)/etc/irony-server/"
+cmake -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=ON \
+      -DCMAKE_INSTALL_PREFIX="$DEST" ../
+cmake --build . --use-stderr --config Release --target install
+
+install_name_tool -change @rpath/libclang.dylib \
+    /usr/local/opt/llvm/lib/libclang.dylib \
+    "$DEST/bin/irony-server"
+
+# cleanup
+popd
+rm -rf irony-mode
 #+END_SRC
 
 *** 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,14 +1,25 @@
-* Go
+* :lang go
 
-Go support, including auto-completion, eldoc support (go-eldoc), REPL support,
+This module adds [[https://golang.org][Go]] support.
-refactoring commands, syntax-checking (flycheck), auto-formatting (gofmt) and
-snippets (yasnippet).
 
-+ [[https://golang.org][Homepage]]
++ Code completion (~gocode~)
-+ [[https://github.com/hlissner/emacs-snippets/tree/master/go-mode][Snippets]]
++ eldoc support (~go-eldoc~)
++ REPL (~gore~)
++ Syntax-checking (~flycheck~)
++ Auto-formatting on save (~gofmt~)
++ Code navigation & refactoring (~go-guru~)
 + [[../../feature/file-templates/templates/go-mode][File templates]]
++ [[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. I like its simplicity and syntax (mostly), 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{}~.
+
+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
+To get started with Go, you need the ~go~ tool:
 
-** Installation
 *** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew install go
@@ -19,15 +30,20 @@ brew install go
 sudo pacman --needed --noconfirm -S go
 #+END_SRC
 
-** Setup
+** Dependencies
-You need to set up ~GOPATH~ before you can install lang/go's dependencies.
+This module requires a valid ~GOPATH~, and the following Go packages:
+
++ ~gocode~ (for code completion)
++ ~gore~ (for the REPL)
++ ~guru~ (for code navigation & refactoring commands)
++ ~gorename~ (for extra refactoring commands)
 
 #+BEGIN_SRC sh
 export GOPATH=~/work/go
 
-go get -u github.com/nsf/gocode            # completion
+go get -u github.com/nsf/gocode
-go get -u github.com/motemen/gore          # REPL
+go get -u github.com/motemen/gore
-go get -u golang.org/x/tools/cmd/guru      # code navigation commands
+go get -u golang.org/x/tools/cmd/guru
-go get -u golang.org/x/tools/cmd/gorename  # refactoring commands
+go get -u golang.org/x/tools/cmd/gorename
 #+END_SRC
 

modules/lang/haskell/README.org

@@ -0,0 +1,64 @@
+* :lang haskell
+
+This module adds [[https://www.haskell.org/][Haskell]] support.
+
++ Code completion (~company-ghc~)
++ Look up documentation (~hoogle~)
++ eldoc support (~dante~)
++ REPL (~ghci~)
++ Syntax-checking (~flycheck~)
++ Code navigation (~dante~)
++ [[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).
+
+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
+To get started with Haskell, you need:
+
++ cabal (the haskell package builder)
++ ghc/ghci (the compiler, syntax checker & repl)
+
+*** MacOS
+#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
+brew install cabal-install ghc
+#+END_SRC
+
+*** Arch Linux
+#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
+sudo pacman --needed --noconfirm -S cabal-install ghc
+#+END_SRC
+
+** Dependencies
+This module requires the following ~cabal~ packages:
+
++ ~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
+cabal install happy haskell-src-exts ghc-mod hoogle
+#+END_SRC
+
+Ensure that ~\~/.cabal/bin~ is in ~PATH~:
+
+#+BEGIN_SRC sh
+# place this in your profile file, like ~/.bash_profile or ~/.zshenv
+export PATH="~/.cabal/bin:$PATH"
+#+END_SRC
+
+** 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
+Here are a few resources I've found indespensible in my Haskell adventures:
+
++ [[http://learnyouahaskell.com/][Learn you a haskell for great good]]
++ [[http://haskellbook.com/][Haskell Programming from first principles]]
++ [[https://github.com/krispo/awesome-haskell][Awesome Haskell]]: an extensive list of haskell resources

modules/lang/php/README.org

@@ -0,0 +1,58 @@
+* :lang php
+
+This module adds support for PHP 5.3+ (including PHP7).
+
++ ctags-based code completion (~company-php~ and ~phpctags~)
++ eldoc support (~ac-php~ and ~php-extras~)
++ REPL (~php-boris~)
++ Code refactoring commands (~php-refactor-mode~)
++ Unit-test commands (~phpunit~)
++ Support for ~laravel~ and ~composer~ projects (with project-specific snippets)
++ [[../../feature/file-templates/templates/php-mode][File templates]]
++ [[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.
+
+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
+To get started with PHP, you'll need ~php~ (5.3+) and ~composer~:
+
+*** MacOS
+PHP 5.5 comes prepackaged with newer versions of MacOS. These instructions are provided for reference:
+
+#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
+brew tap homebrew/homebrew-php
+brew install php71  # or php53, php54, php55
+brew install composer
+#+END_SRC
+
+*** Arch Linux
+#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
+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:
+
++ ~boris~ (REPL)
++ ~phpctags~ (better code completion)
++ ~phpunit~ (unit test commands)
+
+#+BEGIN_SRC sh
+composer global require \
+    d11wtq/boris \
+    phpunit/phpunit \
+    techlivezheng/phpctags
+#+END_SRC
+
+Ensure that ~\~/.composer/vendor/bin~ is in ~PATH~:
+
+#+BEGIN_SRC sh
+# place this in your profile file, like ~/.bash_profile or ~/.zshenv
+export PATH="~/.composer/vendor/bin:$PATH"
+#+END_SRC

modules/lang/rest/README.org

@@ -1,9 +1,51 @@
-* REST
+* :lang rest
 
-On occasion I need to test REST APIs. I will, typically, open up an org buffer,
+This module adds [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] support.
-create a restclient source block and hack away. [[https://github.com/pashky/restclient.el][restclient-mode]] (and
-[[https://github.com/iquiw/company-restclient][company-restclient]] for auto-completion) power this arcane wizardry.
 
-Meanwhile, [[https://github.com/iquiw/company-restclient][ob-restclient]] integrates ~restclient-mode~ into org-babel.
++ Code-completion (~company-restclient~)
++ Code evaluation
++ org-mode: babel support (~ob-restclient~)
 
-There are no external dependencies for this module.
+#+begin_quote
+~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
+No additional setup required.
+
+** Example
+#+BEGIN_SRC restclient
+GET https://jsonplaceholder.typicode.com/posts/1
+#+END_SRC
+
+#+BEGIN_EXAMPLE
+#+RESULTS:
+#+BEGIN_SRC js
+{
+  "userId": 1,
+  "id": 1,
+  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
+  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
+}
+// GET https://jsonplaceholder.typicode.com/posts/1
+// HTTP/1.1 200 OK
+// Date: Thu, 25 May 2017 13:43:42 GMT
+// Content-Type: application/json; charset=utf-8
+// Content-Length: 292
+// Connection: keep-alive
+// Set-Cookie: __cfduid=d3484257c800700f9882305963fa9d5d91495719822; expires=Fri, 25-May-18 13:43:42 GMT; path=/; domain=.typicode.com; HttpOnly
+// X-Powered-By: Express
+// Vary: Origin, Accept-Encoding
+// Access-Control-Allow-Credentials: true
+// Cache-Control: public, max-age=14400
+// Pragma: no-cache
+// Expires: Thu, 25 May 2017 17:43:42 GMT
+// X-Content-Type-Options: nosniff
+// Etag: W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU"
+// Via: 1.1 vegur
+// CF-Cache-Status: HIT
+// Server: cloudflare-nginx
+// CF-RAY: 3648ecd7ef833d0d-CPH
+// Request duration: 0.347179s
+#+END_SRC
+#+END_EXAMPLE

modules/ui/doom-modeline/README.org

@@ -0,0 +1,40 @@
+* :ui doom-modeline
+
+This module customizes the Emacs mode-line.
+
+The DOOM modeline was designed for minimalism, and offers:
+
++ A match count panel (for ~evil-search~, ~iedit~ and ~evil-substitute~)
++ An indicator for recording a macro
++ Local python/ruby version in the major-mode
++ A customizable mode-line height (see ~+doom-modeline-height~)
++ An error/warning count segment for flycheck
+
+[[/../screenshots/ml.png]]
+[[/../screenshots/ml-search.png]]
+[[/../screenshots/ml-subst.png]]
+[[/../screenshots/ml-macro.png]]
+[[/../screenshots/ml-version.png]]
+[[/../screenshots/ml-errors.png]]
+
+** 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
+Some might want my modeline without the DOOM config altogether. I've taken some care to make this as easier for you.
+
+Here is what you must do:
+
++ Ensure [[https://github.com/bbatsov/projectile][projectile]] and [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] are installed
++ Ensure ~projectile-mode~ is enabled
++ 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~
+
+And you /should/ be good to go. 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.
+
+** Troubleshooting
+*** 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.

modules/ui/doom/README.org

@@ -1,26 +1,33 @@
-* DOOM
+* :ui doom
 
-DOOM's look is loosely inspired by Atom's One Dark theme. I've my [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]]
+This module modifies Emacs' user interface.
-plugin to thank for bringing it to Emacs.
 
-On top of that, it uses:
+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.
 
-+ [[https://github.com/mozilla/Fira][Fira Mono]] (font)
+By default, this module uses:
-+ [[https://github.com/rolandwalker/nav-flash][nav-flash]]: blinks the current line when jumping large distances, to help keep
+
-  track of the cursor.
++ [[https://github.com/mozilla/Fira][Fira Mono and Fira Sans]] (fonts)
++ [[https://dejavu-fonts.github.io/][DejaVu Sans Mono]] (font, for displaying unicode characters)
++ [[https://github.com/rolandwalker/nav-flash][nav-flash]]: blinks the current line when jumping large distances, to help keep track of the cursor.
 + ~hideshow~, modified to use a nicer folded-region indicator.
 + Custom fringe bitmaps for ~git-gutter-fringe~ (thin bars)
 
-** Installation
+** Install
 [[https://github.com/mozilla/Fira][Fira Mono]] is this module's only dependency (if you want to use it).
 
 *** MacOS
 #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
 brew tap caskroom/fonts
-brew cask install font-fira-mono
+brew cask install font-fira-{sans,mono} font-dejavu-sans
 #+END_SRC
 
 *** Arch Linux
 #+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
-sudo pacman --noconfirm --needed -S ttf-fira-mono
+sudo pacman --noconfirm --needed -S ttf-fira-{sans,mono} ttf-dejavu
 #+END_SRC
+
+** Troubleshooting
+*** Strange font symbols
+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]]).
+
+You must install the fonts included with ~all-the-icons~ with: ~M-x all-the-icons-install-fonts~.