Update & reformat module readmes for v2.0.9
+ completion/ivy + completion/company + feature/evil + feature/eval + feature/snippets + feature/workspaces + tools/neotree
This commit is contained in:
Henrik Lissner
parent
eef6ed3d11
commit
e87b788078
7 changed files with 138 additions and 81 deletions
|
|
@ -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/<username>/config.el~ module:
|
||||
For example:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(require 'company)
|
||||
|
|
@ -36,8 +39,10 @@ For example, add the following to your ~modules/private/<username>/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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,28 +1,33 @@
|
|||
#+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*
|
||||
** REPLs
|
||||
Invoked via:
|
||||
+ ~:repl~ (evil ex-command)
|
||||
+ =<leader> o r= in normal mode (or visual mode, which sends the selection to the open REPL)
|
||||
+ =<leader> 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*
|
||||
** *Code Evaluation*
|
||||
Quickrun can be invoked via:
|
||||
+ ~M-x +eval/buffer~ (or ~gR~, or ~M-r~)
|
||||
+ ~M-x +eval/region~
|
||||
|
|
@ -31,13 +36,17 @@ Check the README.org in that language's module for details.
|
|||
|
||||
* 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|---------------------------+----------------------------+------------------------------------------------------------|
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue