Standardize module READMEs

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]],
-+ [[#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]].
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#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
-*** REPLs
-REPLs have been defined for most of the languages DOOM supports (check its README.org to see if it does).
+* Configuration
+** REPLs
+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
-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.
+** Build Tasks
+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
-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).
+* Table of Contents :TOC:
+- [[#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
-*** Overview
-+ A better ~:g[lobal]~ command with match highlighting
-+ ~:al[ign]~: an ex interface to ~align-regexp~ with match highlighting
+* Removing evil-mode
+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).
+
+* 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
-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).
+** A hybrid code-folding system
+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.