Update READMEs

README.md

@@ -8,7 +8,7 @@
 </a>
 
 This is an Emacs configuration for a stubborn, melodramatic and
-shell-dwelling vimmer disappointed with the text-editor statsu quo.
+shell-dwelling vimmer disappointed with the text-editor status quo.
 
 Doom tries to look and act like modern editors (whatever that means to
 me on any given day), emulate vim as best it can and strive to surpass
@@ -16,10 +16,7 @@ it in any way possible. I've designed it to fit my needs as a software
 developer, indie game developer, scientist and doom enthusiast.
 
 It was tailored for **MacOS 10.11+** and **Arch Linux 4.7+**, and
-exclusively for Emacs 25.1+ **(NOTE: Older versions of Emacs won't
+**exclusively** for Emacs 25.1+. I use [vim] everywhere else.
-work).**. I use [vim] everywhere else.
-
-**NOTE:** you can [find the theme in a separate repo][doom-theme].
 
 ## Installation
 
@@ -31,18 +28,20 @@ make install
 make compile       # optional, may take a while
 ```
 
-If you change the module list in `init.el`, you'll need to refresh
+Each time you change init.el, you must do the following:
-autoloads and, if necessary, recompile:
 
-+ `make autoloads` or `(doom/reload-autoloads)`
+```bash
-+ If you byte-compiled: `make compile` or `(doom/byte-compile)`
+make install       # or (doom/packages-install)
+make autoloads     # or (doom/reload-autoloads)
+# ...and optionally
+make compile       # or (doom/byte-compile)
+```
 
 ## Deciphering my emacs.d
 
 To get a picture of what's in here, check out:
 
-* **[init.example.el](init.example.el)**: what my init.el looks like.
+* **[init.example.el](init.example.el)**: what my loadout looks like.
-  Copy this to `init.el` and you're set.
 * **[modules/README.md](modules/README.md)**: a primer into module
   structure and how the module system works.
 * **[modules/private/hlissner/+bindings.el](modules/private/hlissner/+bindings.el)**:
@@ -50,21 +49,17 @@ To get a picture of what's in here, check out:
 * **[modules/private/hlissner/+commands.el](modules/private/hlissner/+commands.el)**:
   my custom ex commands.
 * **[modules/ui](modules/ui)**: the modules that makes my Emacs look
-  the way it does, including my modeline, dashboard and more.
+  the way it does, including [my theme][doom-theme], modeline,
-+ See screenshots in the [screenshots branch][sc].
+  dashboard and more.
-+ Some modules have README's.
++ Find screenshots in the [screenshots branch][sc].
 
-### Features
+### Highlights
 
-* Strong support for a [large selection of languages](modules/lang),
+* A [popup management system](core/core-popups.el) using **[shackle]**
-  including REPLs and inline/live code evaluation.
+  for temporary or disposable buffers.
-* A [consistent popup management system](core/core-popups.el) using
+* Workspaces, tab emulation & session persistence with
-  **[shackle]** for temporary or disposable buffers. e.g. help buffers
+  **[persp-mode]**.
-  will always pop up at the bottom of the frame, and are removed with
+* Project and workspace-restricted buffer navigation and functions.
-  ESC.
-* Workspaces, tab emulation and session persistence with
-  **[workgroups2]**.
-* Project and workspace-sensitive buffer navigation and functions.
 * A vim-centric environment with **[evil-mode]**
   * 2-character motions (ala vim-seek/vim-sneak) with **[evil-snipe]**
   * Sublime Text-esque [multiple cursors][sc-multiedit] with
@@ -77,59 +72,46 @@ To get a picture of what's in here, check out:
   * File browser sidebar with **[neotree]**
   * Project search (& replace) with **[counsel-ag]** (and **[wgrep]**)
   * Interactive buffer search with **[swiper]**
-* REPLs & inline/live code evaluation (using **[quickrun]**) for many
+* REPLs & inline/live code evaluation (using **[quickrun]** and
-  languages including Ruby, Python, PHP, JS, Elisp, Haskell and Lua.
+  **[repl-toggle]**) for many languages including Ruby, Python, PHP,
+  JS, Elisp, Haskell and Lua.
 * [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, **[dumb-jump]**, ctags, then **[counsel-ag]**.
 * Snippets and file-templates with **[yasnippet]**.
-* Hybrid completion with both **[company-mode]** and
+* A smarter, perdier, Atom-inspired mode-line that includes:
-  **[auto-complete]**. They collaborate to give you the completion
-  system most appropriate for the current major mode.
-* A modern interface inspired by Atom's, with a smarter, perdier
-  mode-line that includes:
   * evil-search/iedit/evil-substitute mode-line integration
   * Macro-recording indicator
   * Python/ruby version in mode-line (for rbenv/pyenv)
 
 ## Contributing or troubleshooting
 
-My config wasn't designed with anyone else's use in mind, but I'm all
+My config wasn't intended for public use, but I'm happy to help you
-for improving it in any way possible. [Don't hesitate to report bugs
+use or crib from my config and I welcome contributions of any kind;
-or tell me my Elisp-fu sucks](https://github.com/hlissner/.emacs.d/issues/new)!
+documentation, bug fixes or even elisp tips.
 
-If you'd like to help, I'd be happy to accept any sort of
+[Don't hesitate to report bugs or tell me my Elisp-fu sucks](https://github.com/hlissner/.emacs.d/issues/new)!
-contributions, whether that be modules, extra documentation, bug fixes
-or even elisp tips. I don't mind any opportunity to learn more about
-Emacs.
 
 
 [yay-evil]: http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573
 [Cask]: https://github.com/cask/cask
-[Homebrew]: http://brew.sh
 
-[auto-yasnippet]: https://melpa.org/#/auto-yasnippet
 [company-mode]: https://melpa.org/#/company
 [counsel-ag]: https://melpa.org/#/counsel
 [dumb-jump]: https://melpa.org/#/dumb-jump
 [evil-mode]: https://melpa.org/#/evil
 [evil-multiedit]: https://melpa.org/#/evil-multiedit
 [evil-snipe]: https://melpa.org/#/evil-snipe
-[flycheck]: https://melpa.org/#/flycheck
 [git-gutter-fringe]: https://melpa.org/#/git-gutter-fringe
-[irony-mode]: https://github.com/Sarcasm/irony-mode
 [ivy]: https://melpa.org/#/ivy
 [neotree]: https://melpa.org/#/neotree
-[nlinum]: http://elpa.gnu.org/packages/nlinum.html
 [quickrun]: https://melpa.org/#/quickrun
-[racer]: https://github.com/phildawes/racer
-[realgud]: https://melpa.org/#/realgud
 [repl-toggle]: https://melpa.org/#/repl-toggle
 [shackle]: https://melpa.org/#/shackle
 [swiper]: https://melpa.org/#/swiper
 [wgrep]: https://melpa.org/#/wgrep
-[workgroups2]: https://melpa.org/#/workgroups2
+[persp-mode]: https://melpa.org/#/persp-mode
 [yasnippet]: https://melpa.org/#/yasnippet
 
 [sc]: https://github.com/hlissner/.emacs.d/tree/screenshots

modules/README.md

@@ -1,17 +1,27 @@
 # Modules
 
-Though the structure of these modules loosely take after Spacemacs'
+Modules are made up of three (optional) parts:
-notion of layers, they are not meant to be interchangeable. Their
-purpose is _almost_ purely organizational.
 
-The structure of a module is as follows (all files are optional):
++ A `config.el` file, automatically loaded when the module is loaded
+  (through `@doom` or `@require`). It uses `@def-package` calls (thin
+  wrappers around `use-package`) to configure packages.
++ A `packages.el` file filled with `@package` and `@depends-on`
+  declarations. These are purely declarative macros. They populate
+  `doom-packages` and `doom-modules` for the package management
+  system.
++ Either an `autoload.el` file or `autoload/*.el` files, which are
+  scanned by `doom/reload-autoloads` and lazily loaded.
 
-```bash
+The convention for extra config files is to prefix them with a plus
-config.el      # loaded when module is enabled
+(`+git.el`). These are not automatically loaded.
-packages.el    # loaded lazily by DOOM package management
-+*.el          # extra config files (not automatically loaded)
 
-# lazy-loaded functions
+## What modules aren't
-autoload.el
+
-autoload/*.el
+Modules loosely take after Spacemacs' notion of layers, but are not
-```
+meant to be interchangeable. Their purpose is _almost_ purely
+organizational.
+
+The only exception to this are completion modules. Other modules make
+no assumptions about which completion modules are enabled. If company
+isn't installed, company plugins will silently refuse to install, and
+their respective `@def-package` blocks will be ignored.