From e87b7880789b228dc9fadacbcef9dbce315631d0 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sun, 31 Dec 2017 23:07:28 -0500 Subject: [PATCH] Update & reformat module readmes for v2.0.9 + completion/ivy + completion/company + feature/evil + feature/eval + feature/snippets + feature/workspaces + tools/neotree --- modules/completion/company/README.org | 19 +++++---- modules/completion/ivy/README.org | 60 +++++++++++++++++++-------- modules/feature/eval/README.org | 56 +++++++++++++++---------- modules/feature/evil/README.org | 27 ++++++++---- modules/feature/snippets/README.org | 19 +-------- modules/feature/workspaces/README.org | 32 ++++++++++---- modules/tools/neotree/README.org | 6 ++- 7 files changed, 138 insertions(+), 81 deletions(-) diff --git a/modules/completion/company/README.org b/modules/completion/company/README.org index 76e9ad4ac..f2a1bc6fc 100644 --- a/modules/completion/company/README.org +++ b/modules/completion/company/README.org @@ -14,20 +14,23 @@ This module adds code-completion support, powered by [[https://github.com/compan - [[#troubleshooting][Troubleshooting]] * Install -Certain languages may require additional setup, and some languages may have no completion support at all. +Some languages require additional setup, and some languages may have no +completion support at all. Check the README.org in that language's module for details. * Configure ** Auto-completion -By default, I've disabled auto-completion. This is my preference. I prefer to invoke company when I need it by calling ~company-complete~ manually (typically, bound to =C-SPC= in insert mode). However, some may not share my preference. +By default, I've disabled auto-completion. This is my preference. I prefer to +invoke company when I need it by calling ~company-complete~ manually (typically, +bound to =C-SPC= in insert mode). However, some may not share my preference. To enable auto-completion you must: 1. Load ~company~, 2. and change ~company-idle-delay~ to a non-nil float (the default is 0.5) -For example, add the following to your ~modules/private//config.el~ module: +For example: #+BEGIN_SRC emacs-lisp (require 'company) @@ -36,8 +39,10 @@ For example, add the following to your ~modules/private//config.el~ mo #+END_SRC * Troubleshooting -If completion isn't working for you, please consider the following before posting a bug report: +If completion isn't working for you, please consider the following before +posting a bug report: -+ If what you are expecting is popup-as-you-type completion (which is disabled by default), see the "Customize" section above; it includes instructions on how to enable this. -+ Certain languages may have extra dependencies in order for auto-completion to work. Please look for that module's README.org for details. -+ Some languages don't have any auto-completion support. ++ If what you are expecting is popup-as-you-type completion (which is disabled + by default), see the "Configure > Auto-completion" section above, which will + instruct you on how to enable this. ++ Some languages don't have any auto-completion support at all. diff --git a/modules/completion/ivy/README.org b/modules/completion/ivy/README.org index b0732f935..18f399739 100644 --- a/modules/completion/ivy/README.org +++ b/modules/completion/ivy/README.org @@ -3,11 +3,13 @@ This module adds Ivy, a completion backend. #+begin_quote -I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter. +I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's +lighter. #+end_quote + Project-wide search & replace powered by ~rg~ or ~ag~ -+ Project jump-to navigation ala Command-T, Sublime Text's Jump-to-anywhere or Vim's CtrlP plugin. ++ Project jump-to navigation ala Command-T, Sublime Text's Jump-to-anywhere or + Vim's CtrlP plugin. + Ivy integration for ~M-x~, ~imenu~, ~recentf~ and others. + A powerful, interactive in-buffer search using ~swiper~. + Ivy-powered TODO/FIXME navigation @@ -28,7 +30,9 @@ I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's l * Install This module optionally depends on [[https://github.com/BurntSushi/ripgrep][ripgrep]] and [[https://github.com/ggreer/the_silver_searcher][the_silver_searcher]]. -~rg~ is faster, but its results aren't deterministic, neither does it support multiline search or full PCRE, that's where ~ag~ is useful. +~rg~ is faster, but its results aren't deterministic, neither does it support +multiline search or full PCRE (at the time of writing), that's where ~ag~ is +useful. ** MacOS #+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes") @@ -41,37 +45,58 @@ sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher #+END_SRC * Usage -Here is some insight into how I use this module. Keep in mind that the referenced commands and keybindings are defined [[/modules/private/hlissner][in my private module]]. +Here is some insight into how I use this module. ** Project search & replace -Ex interfaces to Ag (the silver searcher) and Rg (ripgrep) are available: ~:ag[!]~ and ~:rg[!]~, or their current-directory counterparts ~:agcwd[!]~ and ~:rgcwd[!]~. +There are four Ex interfaces for the silver searcher and ripgrep. They are: + ++ ~:ag[!]~ ++ ~:agcwd[!]~ ++ ~:rg[!]~ ++ ~:rgcwd[!]~ + +The optional BANG tells ag/rg to include ignored files in the search. And the +\*cwd variant of each command will only search in the current directory +(non-recursively). [[/../screenshots/modules/completion/ivy/ivy-search.gif]] -From this session, you can press =S+Tab= to create a writeable occur-buffer in wgrep mode. +Now, how do we do text replacements? With the ivy popup open you can press +=S+Tab= to create an wgrep buffer out of the results. [[/../screenshots/modules/completion/ivy/ivy-search-replace.gif]] -Make your modifications and press =C-c C-c= to commit them, or =C-c C-k= to abort. +Make your modifications and press =C-c C-c= to commit them, or =C-c C-k= to +abort. ** Jump-to-file project navigation -Inspired by Sublime Text's jump-to-anywhere, Vim's CtrlP or Unite plugins, and Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available to you in Emacs. Invoke it with =SPC f /=, =SPC SPC= or ~counsel-projectile-find-file~. +Inspired by Sublime Text's jump-to-anywhere, Vim's CtrlP/Unite plugins, and +Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available +in Emacs. + +Invoke it with =SPC f /=, =SPC SPC= or ~M-x counsel-projectile-find-file~. [[/../screenshots/modules/completion/ivy/ivy-projectile.gif]] ** In-buffer searching -I use ~evil-search~ (invoked by pressing =/= in normal mode) when jumping small/moderate (or predictable) distances. However, there are occasions where I need more feedback, so I turn to ~swiper~ (available directly with =M-x swiper RET=, or via ~:sw[iper]~). +I use ~evil-search~ (invoked by pressing =/= in normal mode) when jumping +small/moderate (or predictable) distances. However, there are occasions where I +need more feedback, so I turn to ~swiper~ (available directly with =M-x swiper +RET=, or via ~:sw[iper]~). [[/../screenshots/modules/completion/ivy/ivy-swiper.gif]] ** Task lookup -I sprinkle my projects with TODO's & FIXME's. You can navigate to and peruse them via ~M-x +ivy/tasks~ or ~:todo[!]~ (ex command). +I sprinkle my projects with TODO's & FIXME's. You can navigate to and peruse +them via ~M-x +ivy/tasks~ or ~:todo[!]~ (ex command). [[/../screenshots/modules/completion/ivy/ivy-todo.gif]] * Appendix ** Commands -Here is a list of my commonly used commands, their default keybinds (defined in [[../../private/hlissner/+bindings.el][private/hlissner/+bindings.el]]), and their corresponding ex command (defined in [[../../private/hlissner/+commands.el][private/hlissner/+commands.el]]). +Here is a list of my commonly used commands, their default keybinds (defined in +[[../../private/default/+bindings.el][private/default/+bindings.el]]), and their corresponding ex command (defined in +[[../../private/default/+evil-commands.el][private/default/+evil-commands.el]]). | command | key / ex command | description | |-------------------------------------+------------------------+------------------------------------------------------------------| @@ -90,7 +115,8 @@ Here is a list of my commonly used commands, their default keybinds (defined in | ~+ivy:swiper~ | ~:sw[iper] [QUERY]~ | Search current buffer | | ~+ivy:todo~ | ~:todo[!]~ | List all TODO/FIXMEs in project (or current file if BANG) | -While in a search (e.g. invoked from ~+ivy:ag~ or ~+ivy:rg~), these new keybindings are available to you: +While in a search (e.g. invoked from ~+ivy:ag~ or ~+ivy:rg~), these new +keybindings are available to you: | key | description | |-------------+--------------------------------------------------------------------------------| @@ -99,10 +125,10 @@ While in a search (e.g. invoked from ~+ivy:ag~ or ~+ivy:rg~), these new keybindi | =M-RET= | Open the selected candidate in other-window | ** Hacks -+ Functions with ivy/counsel equivalents have been globally remapped (like ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will invoke ~counsel-find-file~ instead. -+ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex command) -+ ~counsel-[arp]g~'s parentheses quoting behavior was reversed. Now, if you - want literal parentheses, you must escape them: e.g. ~\(match\)~ is literal, - ~(match)~ is a regexp group. ++ Functions with ivy/counsel equivalents have been globally remapped (like + ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will + invoke ~counsel-find-file~ instead. ++ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex + command) diff --git a/modules/feature/eval/README.org b/modules/feature/eval/README.org index eb9cf3084..851ea6a48 100644 --- a/modules/feature/eval/README.org +++ b/modules/feature/eval/README.org @@ -1,43 +1,52 @@ #+TITLE: :feature eval -This modules adds support for evaluating code from inside Emacs. This includes REPLs and direct access to the interpreters and compilers of many languages. +This modules adds support for evaluating code from inside Emacs, including +REPLs. * Table of Contents :TOC: - [[#install][Install]] - [[#usage][Usage]] -- [[#configuration][Configuration]] - [[#repls][REPLs]] - - [[#code-evaluation][Code Evaluation]] + - [[#code-evaluation][*Code Evaluation*]] +- [[#configuration][Configuration]] + - [[#repls-1][REPLs]] + - [[#code-evaluation-1][Code Evaluation]] * Install -This module has no external dependencies. However, specific languages may require additional setup. +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 -+ *REPLs* - Invoked via: - + ~:repl~ (evil ex-command) - + = o r= in normal mode (or visual mode, which sends the selection to the open REPL) - + ~M-x +eval/open-repl~ - + ~M-x +eval/send-region-to-repl~ while a selection (and REPL) is active +** REPLs +Invoked via: ++ ~:repl~ (evil ex-command) ++ = o r= in normal mode (or visual mode, which sends the selection to + the open REPL) ++ ~M-x +eval/open-repl~ ++ ~M-x +eval/send-region-to-repl~ while a selection (and REPL) is active -+ *Code Evaluation* - Quickrun can be invoked via: - + ~M-x +eval/buffer~ (or ~gR~, or ~M-r~) - + ~M-x +eval/region~ - + ~M-x +eval/region-and-replace~ - + Evil users can use the ~gr~ operator to select and run a region. +** *Code Evaluation* +Quickrun can be invoked via: ++ ~M-x +eval/buffer~ (or ~gR~, or ~M-r~) ++ ~M-x +eval/region~ ++ ~M-x +eval/region-and-replace~ ++ Evil users can use the ~gr~ operator to select and run a region. * Configuration ** REPLs -REPLs are defined for most of the languages Doom supports (check its README.org to see if it does). +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 for a specified major-mode with the =:repl= setting. +Otherwise, you can define your own for a specified major-mode with the =:repl= +setting. ~(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. +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 () @@ -53,9 +62,14 @@ FUNCTION must return the repl buffer. Any window changes are ignored, then hande #+END_SRC ** Code Evaluation -Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output will be sent to a popup window. +Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output is show in 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: +Quickrun includes support for many languages, usually by sending text directly +to interpreters or compilers. However, occasionally, you'll find a language +without support (like [[https://crystal-lang.org/][Crystal]]), or a language with better Emacs integration +(like elisp). + +Here's how you define a "runner": #+BEGIN_SRC emacs-lisp (set! :eval 'crystal-mode diff --git a/modules/feature/evil/README.org b/modules/feature/evil/README.org index 1ba70d4cb..4093c770a 100644 --- a/modules/feature/evil/README.org +++ b/modules/feature/evil/README.org @@ -11,12 +11,14 @@ This holy module brings the vim experience to Emacs. - [[#differences-from-vim][Differences from vim]] * 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). +See the [[https://github.com/hlissner/doom-emacs/wiki/FAQ#remove-vimevil-for-a-more-vanilla-emacs-experience][corresponding question in the FAQ]]. * 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. ++ 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~) @@ -31,20 +33,29 @@ To get back a more vanilla Emacs experience, remove =:feature evil= from init.el + =NERDTree= equivalent is available in =:tools neotree= ** Multiple-cursors -Two multiple-cursor implementations exist in this module: ~evil-mc~ and ~evil-multiedit~. Together, these provide the functionality of ~vim-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~). +The former lets you place "clone" cursors. The latter lets you interactively +edit many regions at once (like an interactive version of ~:%s~). ** 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. +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. 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. ++ From 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~). ++ 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 incrementally highlight buffer matches. diff --git a/modules/feature/snippets/README.org b/modules/feature/snippets/README.org index 3a81372b6..d22278f1b 100644 --- a/modules/feature/snippets/README.org +++ b/modules/feature/snippets/README.org @@ -8,20 +8,5 @@ This module adds snippets to Emacs, powered by yasnippet. * 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 - +By default, =private/default= installs a snippet library tailored exclusively +for Doom Emacs. diff --git a/modules/feature/workspaces/README.org b/modules/feature/workspaces/README.org index c2e3f2c71..29f8dec1a 100644 --- a/modules/feature/workspaces/README.org +++ b/modules/feature/workspaces/README.org @@ -1,9 +1,15 @@ #+TITLE: :feature workspaces -This module adds support for workspaces, powered by persp_mode, as well as a unified API for manipulating them. +This module adds support for workspaces, powered by persp_mode, as well as a 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. +There are many ways to use workspaces. I spawn a workspace per task. Say I'm +working in the main workspace, when I realize there is a bug in another part of +my project. I open a new workspace and deal with it in there. In the meantime, I +need to check my email, so mu4e gets its own workspace. + +Once I've completed the task, I close the workspace and return to main. #+end_quote * Table of Contents :TOC: @@ -22,25 +28,33 @@ 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~. +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) ++ Create a new frame (with =make-frame=; bound to =M-N= by default). ++ Switch to a project using ~projectile-switch-project~. ** 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). +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. +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~. +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). +Here is a list of available commands, their default keybindings (defined in +[[../../private/default/+bindings.el][private/default/+bindings.el]]), and corresponding ex commands (if any -- defined +in [[../../private/default/+evil-commands.el][private/default/+evil-commands.el]]). | command | key / ex command | description | |---------------------------+----------------------------+------------------------------------------------------------| diff --git a/modules/tools/neotree/README.org b/modules/tools/neotree/README.org index 280a97c3d..efbf410c1 100644 --- a/modules/tools/neotree/README.org +++ b/modules/tools/neotree/README.org @@ -1,7 +1,9 @@ #+TITLE: :evil neotree -This module brings a side panel for browsing project files, inspired by vim's NERDTree. +This module brings a side panel for browsing project files, inspired by vim's +NERDTree. #+begin_quote -Sure, there's dired and projectile, but sometimes I'd like a bird's eye view of a project. +Sure, there's dired and projectile, but sometimes I'd like a bird's eye view of +a project. #+end_quote