Merge branch 'develop'

* develop: (64 commits)
  Prepare for v2.0.5
  Temporarily disable doom-themes-visual-bell-config
  Fix neotree always changing root
  Update changelog
  Fix wrong-type-argument error from +org/insert-item
  Make +ivy-buffer-transformer autoloadable
  General refactor & cleanup
  Correct troubleshooting link in README
  org: set org-ellipsis to downward chevron
  Add elfeed-(show|search)-mode to evil-snipe-disabled-modes
  Autoload json library
  Rethink smartparens config #181
  README: expand troubleshooting
  Fix wiki links in README (again)
  Correct intro in README
  Fix wiki links in README
  Prevent private commands from affecting projectile cache
  Remove recentf-filename-handlers fix for projectile-recentf-files
  lang/sh: remove unused setup.sh
  Convert +ivy/switch-buffer to transformers + add mode icons #169
  ...

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.
 

modules/feature/evil/config.el

@@ -323,6 +323,7 @@ the new algorithm is confusing, like in python or ruby."
         evil-snipe-scope 'line
         evil-snipe-repeat-scope 'visible
         evil-snipe-char-fold t
+        evil-snipe-disabled-modes '(magit-mode elfeed-show-mode elfeed-search-mode)
         evil-snipe-aliases '((?\[ "[[{(]")
                              (?\] "[]})]")
                              (?\; "[;:]")))

modules/feature/file-templates/config.el

@@ -55,6 +55,7 @@
           ("-test\\.el$"                     "__"               emacs-ert-mode)
           ("/.emacs.d/.+\\.el$"              "__doom-module"    emacs-lisp-mode)
           ("/.emacs.d/.+/packages\\.el$"     "__doom-packages"  emacs-lisp-mode)
+          ("/.emacs.d/.+/README\\.org$"      "__doom-readme"    org-mode)
           (snippet-mode "__" snippet-mode)
           ;; Go
           ("\\.go$"                          "__.go"            go-mode)
@@ -78,6 +79,8 @@
           ("/conf\\.lua$"                    "__conf.lua"       love-mode)
           ;; Markdown
           ("\\.md$"                          "__"               markdown-mode)
+          ;; Org
+          ("\\.org$"                         "__"               org-mode)
           ;; PHP
           ("\\.php$"                         "__"               php-mode)
           ("\\.class\\.php$"                 "__.class.php"     php-mode)

modules/feature/file-templates/templates/org-mode/__

@@ -1,6 +1,6 @@
 # -*- mode: snippet -*-
 # name: Org template
 # --
-#+TITLE:${1:`(file-name-base buffer-file-name)`}
+#+TITLE: ${1:`(file-name-base buffer-file-name)`}
 
 $0

modules/feature/file-templates/templates/org-mode/__doom-readme

@@ -0,0 +1,48 @@
+# -*- mode: snippet -*-
+# name: Doom module readme
+# --
+#+TITLE: ${1:`(progn (string-match "modules/\\([^/]+\\)/\\([^/]+\\)/.+" buffer-file-name)
+                (format ":%s %s"
+                   (match-string 1 buffer-file-name)
+                   (match-string 2 buffer-file-name)))`}
+                   
+${2:A short summary about what this module does.}
+
+${3:If necessary, include a longer description below it that goes into more detail. This may be as long as you like.
+
++ If possible, include a list of features
++ Include links to major plugins that the module uses, if applicable
++ Use links whenever you can
++ Mention dependencies on other modules here}
+
+* Table of Contents :TOC:
+
+* Install
+** Main dependencies
+*** MacOS
+#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
+brew install x
+#+END_SRC
+
+*** Arch Linux
+#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
+sudo pacman --needed --noconfirm -S X
+#+END_SRC
+
+** Extra Dependencies
++ A
++ B
++ C
+
+#+BEGIN_SRC sh
+Y install A B C
+#+END_SRC
+
+* Configuration
+
+* Usage
+
+* Appendix
+** Commands
+** Hacks
+$0

modules/feature/snippets/README.org

@@ -0,0 +1,27 @@
+#+TITLE: :feature snippets
+
+This module adds snippets to Emacs, powered by yasnippet.
+
+* Table of Contents :TOC:
+- [[#install][Install]]
+
+* Install
+There are no extra dependencies for this module.
+
+By default, this module uses the snippet library included with yasnippet.
+
+For the best experience, I'd suggest installing mine from https://github.com/hlissner/emacs-snippets -- they have been tailored specifically for Doom.
+
+1. Clone the repo to your private module:
+   #+BEGIN_SRC bash
+   git clone https://github.com/hlissner/emacs-snippets ~/.emacs.d/modules/private/$(whoami)/snippets
+   #+END_SRC
+2. Tell yasnippet where to look for them:
+   #+BEGIN_SRC emacs-lisp
+   ;; modules/private/{USERNAME}/config.el
+   (after! yasnippet
+     (setq yas-snippet-dirs
+           (append (list (expand-file-name "snippets/" (file-name-directory load-file-name)))
+                   (delq 'yas-installed-snippets-dir yas-snippet-dirs))))
+   #+END_SRC
+

modules/feature/version-control/config.el

@@ -1,12 +1,17 @@
 ;;; feature/version-control/config.el -*- lexical-binding: t; -*-
 
+(unless (featurep! -git)
+  (load! +git))
+;; TODO hg support
+;; (unless (featurep! -hg)
+;;   (load! +hg))
+
+;;
 (setq vc-make-backup-files nil)
 
 (defvar +vcs-auto-hydra-smerge t
   "When entering `smerge-mode' automatically open associated hydra.")
 
-(load! +git)
-;; (load! +hg)
 
 (after! vc-annotate
   (set! :popup

modules/feature/version-control/packages.el

@@ -5,11 +5,12 @@
 ;; n/a
 
 ;;; +git
-(package! git-gutter-fringe)
-(package! git-link)
-(package! git-timemachine)
-(package! gitconfig-mode)
-(package! gitignore-mode)
-(package! magit)
+(unless (featurep! -git)
+  (package! git-gutter-fringe)
+  (package! git-link)
+  (package! git-timemachine)
+  (package! gitconfig-mode)
+  (package! gitignore-mode)
+  (package! magit))
 
 ;;; TODO +hg

modules/feature/workspaces/README.org

@@ -0,0 +1,75 @@
+#+TITLE: :feature workspaces
+
+This module adds support for workspaces, powered by persp_mode, as well as a unified API for manipulating them.
+
+#+begin_quote
+There are many ways to use workspaces. Some use them to group buffers/windows by project or categories (views, models, logic, etc). I use them differently: on a per-task basis, which may traverse multiple projects or aspects, but are tied to an objective. For example: implement a specific feature or fix a certain bug; sometimes unrelated to the project at hand.
+#+end_quote
+
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#features][Features]]
+  - [[#isolated-buffer-list][Isolated buffer-list]]
+  - [[#automatic-workspaces][Automatic workspaces]]
+  - [[#session-persistence][Session persistence]]
+  - [[#workspace-persistence][Workspace persistence]]
+- [[#appendix][Appendix]]
+  - [[#commands--keybindings][Commands & Keybindings]]
+  - [[#api][API]]
+
+* Install
+This module has no additional dependencies.
+
+* Features
+** Isolated buffer-list
+When persp-mode is active, ~doom-buffer-list~ becomes workspace-restricted. You can overcome this by using ~buffer-list~.
+
+** Automatic workspaces
+A workspace is automatically created (and switched to) when you:
+
++ Create a new frame (with =make-frame=; bound to =M-N= by default)
++ Switch to a project using ~projectile-switch-project~ (or its ivy/helm equivalents)
+
+** Session persistence
+By default, your session is autosaved when you quit Emacs (or disable ~persp-mode~). You can load a previous session with ~M-x +workspace/load-session~ or ~:sl[oad]~ (ex command).
+
+You can supply either a name to load a specific session to replace your current one.
+
+** Workspace persistence
+If you'd like to save a specific workspace, use ~M-x +workspace/save~, which can be loaded into the current session (as another workspace) with ~M-x +workspace/load~.
+
+* Appendix
+** Commands & Keybindings
+Here is a list of available commands, their default keybindings (defined in private/hlissner/+bindings.el), and corresponding ex commands (if any -- defined in private/hlissner/+commands.el).
+
+| command                   | key / ex command           | description                                                |
+|---------------------------+----------------------------+------------------------------------------------------------|
+| ~+workspace/new~          | =SPC TAB n=                | Create a new, blank workspace                              |
+| ~+workspace/display~      | =SPC TAB TAB=              | Display open workspaces in the mode-line                   |
+| ~+workspace/load~         | =SPC TAB l=                | Load a saved workspace into the current session            |
+| ~+workspace/load-session~ | =SPC TAB L= / =:sl[oad]=   | Replace current session with a saved one                   |
+| ~+workspace/save~         | =SPC TAB s=                | Save the current workspace to a file                       |
+| ~+workspace/save-session~ | =SPC TAB S= / =:ss[ave]=   | Save current session                                       |
+| ~+workspace/switch-to~    | =SPC TAB .=                | Switch to an open workspace                                |
+| ~+workspace/switch-left~  | =SPC TAB [= / =[ w= / =gT= | Switch to previous workspace                               |
+| ~+workspace/switch-right~ | =SPC TAB [= / =] w= / =gt= | Switch to next workspace                                   |
+| ~+workspace/kill-session~ | =SPC TAB X= / =:sclear=    | Clears the current session (kills all windows and buffers) |
+
+** API
++ ~+workspace-list~ -> list<Struct>
++ ~+workspace-list-names~ -> list<string>
++ ~+workspace-buffer-list &optional PERSP~ -> bool
++ ~+workspace-p OBJ~ -> bool
++ ~+workspace-exists-p NAME~ -> bool
++ ~+workspace-get NAME &optional NOERROR~ -> Struct
++ ~+workspace-current &optional FRAME WINDOW~ -> Struct
++ ~+workspace-current-name~ -> string
++ ~+workspace-load NAME~
++ ~+workspace-load-session NAME~
++ ~+workspace-save NAME~
++ ~+workspace-save-session NAME~
++ ~+workspace-new NAME~
++ ~+workspace-rename NAME NEW-NAME~
++ ~+workspace-delete NAME &optional INHIBIT-KILL-P~
++ ~+workspace-switch NAME &optional AUTO-CREATE-P~
++ ~+workspace-protected-p NAME~ -> bool

modules/feature/workspaces/autoload/workspaces.el

@@ -459,12 +459,6 @@ the workspace and move to the next."
   (+workspace/new)
   (set-frame-parameter frame 'assoc-persp (+workspace-current-name)))
 
-;;;###autoload
-(defun +workspaces|create-project-workspace ()
-  "Create a new workspace when switching project with `projectile'."
-  (when persp-mode
-    (+workspace-switch (projectile-project-name) t)))
-
 ;;;###autoload
 (defun +workspaces|delete-associated-workspace-maybe (frame)
   "Delete workspace associated with current frame IF it has no real buffers."
@@ -480,3 +474,15 @@ the workspace and move to the next."
     (when (doom-real-buffer-list)
       (apply orig-fn args))
     t)
+
+;;;###autoload
+(defun +workspaces*switch-project-by-name (orig-fn &rest args)
+  "Switch to a project and prompt for a file to open.
+
+Ensures the scratch (or dashboard) buffers are CDed into the project's root."
+  (when persp-mode
+    (+workspace-switch (car args) t)
+    (with-current-buffer (switch-to-buffer (doom-fallback-buffer))
+      (setq default-directory (car args))))
+  (apply orig-fn args))
+

modules/feature/workspaces/config.el

@@ -10,7 +10,7 @@
 ;; load the last autosaved session. You can give sessions a custom name so they
 ;; can be loaded later.
 ;;
-;; FYI persp-mode requires `workgroups' for file persistence in Emacs 24.4.
+;; NOTE persp-mode requires `workgroups' for file persistence in Emacs 24.4.
 
 (defvar +workspaces-main "main"
   "The name of the primary and initial workspace, which cannot be deleted or
@@ -41,16 +41,17 @@ renamed.")
         persp-auto-save-opt (if noninteractive 0 1))
 
   ;; Bootstrap
-  (add-hook 'doom-init-hook #'+workspaces|init)
+  (add-hook 'doom-post-init-hook #'+workspaces|init)
   (add-hook 'after-make-frame-functions #'+workspaces|init)
 
   (define-key persp-mode-map [remap delete-window] #'+workspace/close-window-or-workspace)
 
-  ;; per-frame workspaces
+  ;; per-frame and per-project workspaces
   (setq persp-init-new-frame-behaviour-override nil
-        persp-interactive-init-frame-behaviour-override #'+workspace-on-new-frame)
-  (add-hook 'projectile-before-switch-project-hook #'+workspaces|create-project-workspace)
+        persp-interactive-init-frame-behaviour-override #'+workspace-on-new-frame
+        projectile-switch-project-action #'projectile-find-file)
   (add-hook 'delete-frame-functions #'+workspaces|delete-associated-workspace-maybe)
+  (advice-add #'projectile-switch-project-by-name :around #'+workspaces*switch-project-by-name)
 
   ;; only auto-save when real buffers are present
   (advice-add #'persp-asave-on-exit :around #'+workspaces*autosave-real-buffers)