Update READMEs

README.md

@@ -1,143 +1,108 @@
 [![Main screenshot](https://raw.githubusercontent.com/hlissner/.emacs.d/screenshots/main.png?raw=true)][sc]
 
 [![MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
-[![DOOM v1.3.0](https://img.shields.io/badge/DOOM-v1.3.0-blue.svg)](./init.el)
+[![DOOM v2.0.0](https://img.shields.io/badge/DOOM-v2.0.0-blue.svg)](./init.el)
 
 <a href="http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573">
   <img src="https://raw.githubusercontent.com/hlissner/.emacs.d/screenshots/cacochan.png" align="right" />
 </a>
 
 This is an Emacs configuration for a stubborn, melodramatic and
-shell-dwelling vimmer disappointed with the text-editor status quo.
+shell-dwelling vimmer disappointed with the text-editor statsu quo.
 
-Doom tries to look and act like modern editors (whatever that will
+Doom tries to look and act like modern editors (whatever that means to
-mean to me on any given day), emulates vim as best it can and strives
+me on any given day), emulate vim as best it can and strive to surpass
-to surpass it in any way possible. All to fit my needs as a software
+it in any way possible. I've designed it to fit my needs as a software
-developer, indie game developer, UX designer, scientist and doom
+developer, indie game developer, scientist and doom enthusiast.
-enthusiast.
 
-It was tailored for GUI Emacs 25+ on **OSX 10.11+** and
+It was tailored for **MacOS 10.11+** and **Arch Linux 4.7+**, and
-**Arch Linux 4.7+**. I use [vim] everywhere else.
+exclusively for Emacs 25.1+ **(NOTE: Older versions of Emacs won't
+work).**. I use [vim] everywhere else.
 
 **NOTE:** you can [find the theme in a separate repo][doom-theme].
 
 ## Installation
 
-Depends on [Cask] and make:
-
 ```bash
 git clone https://github.com/hlissner/.emacs.d ~/.emacs.d
 cd ~/.emacs.d
-make          # installs plugins via cask and generates autoloads
+cp init.example.el init.el  # maybe edit init.el
-
+make install
-# OPTIONAL
+make compile       # optional, may take a while
-make compile  # compiles core and autoloaded files
-make snippets # install hlissner/emacs-snippets into private/snippets
 ```
 
-Run `:bc!` for a more comprehensive byte compile (`:bc` will compile
+If you change the module list in `init.el`, you'll need to refresh
-the current, open *.el file).
+autoloads and, if necessary, recompile:
 
-For OSX users, I recommend Yukihiro Matsumoto's fork of Emacs, which
++ `make autoloads` or `(doom/reload-autoloads)`
-you can get through homebrew:
++ If you byte-compiled: `make compile` or `(doom/byte-compile)`
 
-```bash
+## Deciphering my emacs.d
-brew tap railwaycat/emacsmacport
-brew install emacs-mac --with-imagemagick --with-modern-icon --HEAD
-```
-
-## Features
 
 To get a picture of what's in here, check out:
 
-* **[The Caskfile](Cask)**: lists installed plugins & where they're
+* **[init.example.el](init.example.el)**: what my init.el looks like.
-  configured.
+  Copy this to `init.el` and you're set.
-* **[init.el](init.el)**: birds-eye view of loaded modules and load
+* **[modules/README.md](modules/README.md)**: a primer into module
-  order.
+  structure and how the module system works.
-* **[core/core-modeline.el](core/core-modeline.el)**: my modeline
+* **[modules/private/hlissner/+bindings.el](modules/private/hlissner/+bindings.el)**:
-  config.
+  my custom keybinds.
-* **[private/my-bindings.el](private/my-bindings.el)**: most of my
+* **[modules/private/hlissner/+commands.el](modules/private/hlissner/+commands.el)**:
-  custom keybinds.
+  my custom ex commands.
-* **[private/my-commands.el](private/my-commands.el)**: custom ex
+* **[modules/ui](modules/ui)**: the modules that makes my Emacs look
-  commands.
+  the way it does, including my modeline, dashboard and more.
-* **[ext/*.sh](ext/)**: scripts that will set up external
++ See screenshots in the [screenshots branch][sc].
-  dependencies, such as [irony-mode] or [racer].
++ Some modules have README's.
 
-See screenshots in the [screenshots branch][sc].
+### Features
 
-### Highlights
+* Strong support for a [large selection of languages](modules/lang),
-
+  including REPLs and inline/live code evaluation.
-* Strong support for a large selection of languages, including C/C++,
+* A [consistent popup management system](core/core-popups.el) using
-  Ruby, Python, PHP, JS, Elisp, Haskell, Lua, Julia, Go, Crystal,
+  **[shackle]** for temporary or disposable buffers. e.g. help buffers
-  Assembly, Java, Swift, (Ba|z)?sh, Scala, Rust, LaTeX, Processing,
+  will always pop up at the bottom of the frame, and are removed with
-  Octave, and more!
+  ESC.
-* Tamed popup windows with **[shackle]**. e.g. help buffers will
+* Workspaces, tab emulation and session persistence with
-  always pop up at the bottom of the frame, and are removed with ESC.
+  **[workgroups2]**.
-* Workspaces & session persistence with **[workgroups2]**.
+* Project and workspace-sensitive buffer navigation and functions.
-* Project and workspace-sensitive buffer navigation and functions
+* A vim-centric environment with **[evil-mode]**
-* A vim-like environment with **[evil-mode]**
+  * 2-character motions (ala vim-seek/vim-sneak) with **[evil-snipe]**
-  * vim-seek/vim-sneak functionality with **[evil-snipe]** (2-char
+  * Sublime Text-esque [multiple cursors][sc-multiedit] with
-    motions)
+    **[evil-multiedit]**
-  * [Multiple cursors][sc-multiedit] with **[evil-multiedit]**
   * Repeat (most) motions with <kbd>SPC</kbd> and
     <kbd>shift</kbd>+<kbd>SPC</kbd> (backwards)
-  * On-the-fly keybindings with `:[nviom]map`
+  * Global <kbd>C-x</kbd> omnicompletion
-  * Global <kbd>C-x</kbd> omnicompletion (e.g.
-    <kbd>C-x</kbd>+<kbd>C-f</kbd> for files)
 * Fast search utilities:
   * Project and buffer navigation with **[ivy]**
   * File browser sidebar with **[neotree]**
-  * Project search (and replace) with **[counsel-ag]** (and
+  * Project search (& replace) with **[counsel-ag]** (and **[wgrep]**)
-    **[wgrep]**)
+  * Interactive buffer search with **[swiper]**
-  * Buffer search with **[swiper]**
+* REPLs & inline/live code evaluation (using **[quickrun]**) for many
-* REPLs for many languages including Ruby, Python, PHP, JS, Elisp,
+  languages including Ruby, Python, PHP, JS, Elisp, Haskell and Lua.
-  Haskell and Lua.
 * [Minimalistic diffs in the fringe][sc-diffs] with **[git-gutter-fringe]**.
-* Modded **org-mode** to be a modern note-taking/LaTeX/word-processing
+* A do-what-I-mean jump-to-definition implementation that tries its
-  platform. (WIP)
+  darnest to find the definition of what you're looking at. It tries
-* Code debugging interface with **[realgud]** (currently supports gdb,
+  major-mode commands, **[dumb-jump]**, ctags, then **[counsel-ag]**.
-  trepanjs, bashdb and zshdb, working on Python/Ruby support)
+* Snippets and file-templates with **[yasnippet]**.
-* A do-what-I-mean jump-to-definition implementation that either uses
+* Hybrid completion with both **[company-mode]** and
-  major-mode commands or falls back to **[dumb-jump]**/ctags.
+  **[auto-complete]**. They collaborate to give you the completion
-* A [pretty mode-line](core/core-modeline.el) inspired by Atom's. It
+  system most appropriate for the current major mode.
-  includes:
+* 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
 
-### Other features
+My config wasn't designed with anyone else's use in mind, but I'm all
+for improving it in any way possible. [Don't hesitate to report bugs
+or tell me my Elisp-fu sucks](https://github.com/hlissner/.emacs.d/issues/new)!
 
-* Line numbers + highlight with **[nlinum]**
+If you'd like to help, I'd be happy to accept any sort of
-* On-demand [platform agnostic] shell with **eshell**
+contributions, whether that be modules, extra documentation, bug fixes
-* Consistent marker-based code-folding with **hideshow**
+or even elisp tips. I don't mind any opportunity to learn more about
-* Inline code execution anywhere (once or live) with **[quickrun]**
+Emacs.
-* Snippet expansion and file templates with **[yasnippet]**
-* Completion with **[company-mode]**
-* Syntax checking with **[flycheck]**
-* Custom O/S interaction commands, like **os-reveal** and
-  **os-open-in-browser**
-* Custom TODO, FIXME and NOTE highlighting and search (`:todo`)
-* **big-mode** for presentations and demonstrations (`:big`)
-* Tmux integration with `:t` and `:tcd` ex commands
-
-
-## Troubleshooting
-
-Though this wasn't designed with anyone else's use in mind, I'd be
-happy to help anyone out with problems encountered using (or cribbing
-from) my config. [Don't hesitate to report bugs](https://github.com/hlissner/.emacs.d/issues/new)!
-
-A few things to keep in mind:
-
-1. **Cask can be flakey, especially with new builds.** If you're
-   getting odd errors when starting up Emacs, try to run `make
-   install` again. I've also had cryptic cask errors that I had to
-   reboot to resolve. YMMV.
-2. If you add new functions to any of the autoloaded
-   `(core|modules)/defuns/*.el` library files, run `make autoloads`
-   afterwards. `:reload` will reload Emacs' load-path if you have
-   Emacs open while doing so.
 
 
 [yay-evil]: http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573

modules/README.md

@@ -0,0 +1,17 @@
+# Modules
+
+Though the structure of these modules loosely take after Spacemacs'
+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):
+
+```bash
+config.el      # loaded when module is enabled
+packages.el    # loaded lazily by DOOM package management
++*.el          # extra config files (not automatically loaded)
+
+# lazy-loaded functions
+autoload.el
+autoload/*.el
+```