Update READMEs & add new ones

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
-[[https://github.com/Sarcasm/irony-mode][irony plugin]] for auto-completion, eldoc documentation and syntax checking (with
-flycheck).
+This module adds support for the C-family of languages: C, C++, and Objective-C.
 
-Though it provides Objective-C support, I don't use it except to inspect
-generated glue code for iOS mobile apps.
++ Code completion (~company-irony~)
++ 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]])
-+ File templates ([[../../feature/file-templates/templates/c-mode][c-mode]], [[../../feature/file-templates/templates/c++-mode][c++-mode]])
+#+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).
 
-** Installation
-~irony-server~ is required to use irony-mode's features auto-completion (among
-other things).
+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
 
-To install it, run ~M-x irony-install-server~, which requires ~cmake~ and
-~libclang~.
+** Install
+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,
-refactoring commands, syntax-checking (flycheck), auto-formatting (gofmt) and
-snippets (yasnippet).
+This module adds [[https://golang.org][Go]] support.
 
-+ [[https://golang.org][Homepage]]
-+ [[https://github.com/hlissner/emacs-snippets/tree/master/go-mode][Snippets]]
++ Code completion (~gocode~)
++ 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
-You need to set up ~GOPATH~ before you can install lang/go's dependencies.
+** 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/motemen/gore          # REPL
-go get -u golang.org/x/tools/cmd/guru      # code navigation commands
-go get -u golang.org/x/tools/cmd/gorename  # refactoring commands
+go get -u github.com/nsf/gocode
+go get -u github.com/motemen/gore
+go get -u golang.org/x/tools/cmd/guru
+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,
-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.
+This module adds [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] support.
 
-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