From 11793094ba4b165aabf961fb23760e5650f3bfdf Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sat, 16 Oct 2021 01:21:31 +0200 Subject: [PATCH] docs(:completion): update READMEs to new format --- modules/completion/README.org | 19 +- modules/completion/company/README.org | 165 +++++++------- modules/completion/helm/README.org | 229 ++++++++++--------- modules/completion/ido/README.org | 58 +++++ modules/completion/ido/config.el | 4 +- modules/completion/ivy/README.org | 228 ++++++++++--------- modules/completion/vertico/README.org | 314 ++++++++++++++------------ 7 files changed, 575 insertions(+), 442 deletions(-) create mode 100644 modules/completion/ido/README.org diff --git a/modules/completion/README.org b/modules/completion/README.org index bd693bf38..4e6acb52c 100644 --- a/modules/completion/README.org +++ b/modules/completion/README.org @@ -1,10 +1,19 @@ -← [[doom-module-index:][Back to module index]] ↙ [[doom-changelog-search:::completion nil][Changelog]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:completion][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] -------------------------------------------------------------------------------- -#+TITLE: :completion -#+DATE: July 29, 2021 -#+SINCE: v21.12.0 -#+SETUPFILE: ../../docs/.setupfile.org +#+TITLE: :completion +#+CREATED: July 29, 2021 +#+SINCE: 21.12.0 * Description These modules provide interfaces and frameworks completion, including code completion. +* Frequently asked questions +** Should I choose Ivy, Helm, Vertico, or Ido? +:PROPERTIES: +:ID: 4f36ae11-1da8-4624-9c30-46b764e849fc +:END: +Vertico is Doom's default and comes highly recommended of the four. It is the +fastest, best integrated in Doom's ecosystem, and its module is the most +actively maintained of the four. It also has the cleanest codebase and ties into +native functionality already existing in Emacs, rather than reinventing the +wheel. diff --git a/modules/completion/company/README.org b/modules/completion/company/README.org index 7e581ca31..375e3f319 100644 --- a/modules/completion/company/README.org +++ b/modules/completion/company/README.org @@ -1,92 +1,99 @@ -#+TITLE: completion/company -#+DATE: February 19, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion company][Issues]] ↖ [[doom-module-source:completion/company][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :completion company +#+SUBTITLE: The ultimate code completion backend +#+CREATED: February 19, 2017 +#+SINCE: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#code-completion][Code completion]] - - [[#vim-esque-omni-completion-prefix-c-x][Vim-esque omni-completion prefix (C-x)]] -- [[#configuration][Configuration]] - - [[#enable-company-backends-in-certain-modes][Enable company backend(s) in certain modes]] -- [[#troubleshooting][Troubleshooting]] - - [[#x-mode-doesnt-have-code-completion-support-or-requires-extra-setup][X-mode doesn't have code completion support or requires extra setup.]] - - [[#no-backends-or-the-incorrect-ones-have-been-registered-for-x-mode][No backends (or the incorrect ones) have been registered for X-mode.]] - -* Description -This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required -for code completion in many of Doom's :lang modules. +* Description :unfold: +This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. Many of Doom's +[[doom-module:][:lang]] modules require it for "intellisense" functionality. https://assets.doomemacs.org/completion/company/overlay.png -** Module Flags -+ =+childframe= Enables displaying completion candidates in a child frame, - rather than an overlay or tooltip (among with other UI enhancements). *This - requires GUI Emacs 26.1+ and is incompatible with the =+tng= flag* -+ =+tng= Enables completion using only ~TAB~. Pressing ~TAB~ will select the - next completion suggestion, while ~S-TAB~ will select the previous one. *This - is incompatible with the =+childframe= flag* +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/company-mode/company-mode][company-mode]] -+ [[https://github.com/hlissner/emacs-company-dict][company-dict]] -+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=) +[[doom-contrib-maintainer:][Become a maintainer?]] +** Module flags +- +childframe :: + Display completion candidates in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or + tooltip. *Requires GUI Emacs.* +- +tng :: + Invoke completion on [[kbd:][TAB]] instad of [[kbd:][C-SPC]]. When company is active, [[kbd:][TAB]] and + [[kbd:][S-TAB]] will navigate the completion candidates. -* Prerequisites -This module has no direct prerequisites. +** Packages +- [[doom-package:][company-box]] if [[doom-module:][+childframe]] +- [[doom-package:][company-dict]] +- [[doom-package:][company-mode]] -However, some major modes may require additional setup for code completion to -work in them. Some major modes may have no completion support at all. Check that -major mode's module's documentation for details. +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has no direct requirements, but some languages may have their own +requirements to fulfill before you get code completion in them (and some +languages may lack code completion support altogether). Run ~$ doom doctor~ to +find out if you're missing any dependencies. + +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Code completion By default, completion is triggered after a short idle period or with the -=C-SPC= key. While the popup is visible, the following keys are available: +[[kbd:][C-SPC]] key. While the popup is visible, the following keys are available: | Keybind | Description | |---------+------------------------------------------| -| =C-n= | Go to next candidate | -| =C-p= | Go to previous candidate | -| =C-j= | (evil) Go to next candidate | -| =C-k= | (evil) Go to previous candidate | -| =C-h= | Display documentation (if available) | -| =C-u= | Move to previous page of candidates | -| =C-d= | Move to next page of candidates | -| =C-s= | Filter candidates | -| =C-S-s= | Search candidates with helm/ivy | -| =C-SPC= | Complete common | -| =TAB= | Complete common or select next candidate | -| =S-TAB= | Select previous candidate | +| [[kbd:][C-n]] | Go to next candidate | +| [[kbd:][C-p]] | Go to previous candidate | +| [[kbd:][C-j]] | (evil) Go to next candidate | +| [[kbd:][C-k]] | (evil) Go to previous candidate | +| [[kbd:][C-h]] | Display documentation (if available) | +| [[kbd:][C-u]] | Move to previous page of candidates | +| [[kbd:][C-d]] | Move to next page of candidates | +| [[kbd:][C-s]] | Filter candidates | +| [[kbd:][C-S-s]] | Search candidates with helm/ivy | +| [[kbd:][C-SPC]] | Complete common | +| [[kbd:][TAB]] | Complete common or select next candidate | +| [[kbd:][S-TAB]] | Select previous candidate | ** Vim-esque omni-completion prefix (C-x) In the spirit of Vim's omni-completion, the following insert mode keybinds are available to evil users to access specific company backends: +| Keybind | Description | +|---------+-----------------------------------| +| [[kbd:][C-x C-]]​] | Complete etags | +| [[kbd:][C-x C-f]] | Complete file path | +| [[kbd:][C-x C-k]] | Complete from dictionary/keyword | +| [[kbd:][C-x C-l]] | Complete full line | +| [[kbd:][C-x C-o]] | Invoke complete-at-point function | +| [[kbd:][C-x C-n]] | Complete next symbol at point | +| [[kbd:][C-x C-p]] | Complete previous symbol at point | +| [[kbd:][C-x C-s]] | Complete snippet | +| [[kbd:][C-x s]] | Complete spelling suggestions | -| Keybind | Description | -|-----------+-----------------------------------| -| =C-x C-]= | Complete etags | -| =C-x C-f= | Complete file path | -| =C-x C-k= | Complete from dictionary/keyword | -| =C-x C-l= | Complete full line | -| =C-x C-o= | Invoke complete-at-point function | -| =C-x C-n= | Complete next symbol at point | -| =C-x C-p= | Complete previous symbol at point | -| =C-x C-s= | Complete snippet | -| =C-x s= | Complete spelling suggestions | +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Enable company backend(s) in certain modes The ~set-company-backend!~ function exists for setting ~company-backends~ buffer-locally in MODES, which is either a major-mode symbol, a minor-mode symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for those modes. -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (after! js2-mode (set-company-backend! 'js2-mode 'company-tide 'company-yasnippet)) @@ -97,20 +104,18 @@ those modes. (after! cc-mode (set-company-backend! 'c-mode '(:separate company-irony-c-headers company-irony))) -#+END_SRC +#+end_src To unset the backends for a particular mode, pass ~nil~ to it: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (after! sh-script (set-company-backend! 'sh-mode nil)) -#+END_SRC +#+end_src * Troubleshooting -If code completion isn't working for you, consider the following common causes -before you file a bug report: +[[doom-report:][Report an issue?]] -** X-mode doesn't have code completion support or requires extra setup. +** X-mode doesn't have code completion support or requires extra setup There is no guarantee your language mode will have completion support. Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may @@ -120,11 +125,19 @@ requires that you have a Robe server running (~M-x robe-start~). Check the relevant module's documentation for this kind of information. -** No backends (or the incorrect ones) have been registered for X-mode. -Doom expects every mode to have an explicit list of company-backends (and as +** No backends (or the incorrect ones) have been registered for X-mode +Doom expects every mode to have an explicit list of ~company-backends~ (and as short a list as possible). This may mean you aren't getting all the completion you want or any at all. -Check the value of ~company-backends~ (=SPC h v company-backends=) from that -mode to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for -details on changing what backends are available for that mode. +Check the value of ~company-backends~ ([[kbd:][SPC h v company-backends]]) from that mode +to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for details +on changing what backends are available for that mode. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/helm/README.org b/modules/completion/helm/README.org index 17ae807e7..21645fedc 100644 --- a/modules/completion/helm/README.org +++ b/modules/completion/helm/README.org @@ -1,169 +1,184 @@ -#+TITLE: completion/helm -#+DATE: January 22, 2021 -#+SINCE: v2.0 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion helm][Issues]] ↖ [[doom-module-source:completion/helm][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :completion helm +#+SUBTITLE: A tank for hunting a house fly +#+CREATED: February 24, 2021 +#+SINCE: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#jump-to-navigation][Jump-to navigation]] - - [[#project-search--replace][Project search & replace]] - - [[#search][Search]] - - [[#replace][Replace]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#helm-integration-for-various-completing-commands][Helm integration for various completing commands]] - - [[#general][General]] - - [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]] - - [[#search-1][Search]] -- [[#configuration][Configuration]] - - [[#icons][Icons]] - - [[#posframe][Posframe]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module provides Helm integration for a variety of Emacs commands, as well +as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep][Ripgrep]]. -* Description -This module provides Helm integration for a variety of Emacs commands, as well as -a unified interface for project search and replace, powered by ripgrep. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] +** Module flags +- +childframe :: + Display Helm windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires + GUI Emacs.* +- +fuzzy :: + Enable fuzzy completion for Helm searches. +- +icons :: + Display icons on completion results (where possible) using either + [[doom-package:][all-the-icons]] or [[doom-package:][treemacs]] iconsets. + +** Packages +- [[doom-package:][helm]] +- [[doom-package:][helm-company]] +- [[doom-package:][helm-c-yasnippet]] +- [[doom-package:][helm-descbinds]] +- [[doom-package:][helm-describe-modes]] +- [[doom-package:][helm-flx]]* if [[doom-module:][+fuzzy]] +- [[doom-package:][helm-icons]]* if [[doom-module:][+icons]] +- [[doom-package:][helm-org]]* if [[doom-module:][:lang org]] +- [[doom-package:][helm-posframe]]* if [[doom-module:][+childframe]] +- [[doom-package:][helm-projectile]] +- [[doom-package:][helm-rg]] +- [[doom-package:][helm-swiper]] + +** TODO Hacks #+begin_quote -I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's -lighter, simpler and faster in many cases. + 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] #+end_quote -Ivy is considered a first-class citizen in Doom, however it is still possible to use Helm if you so desire. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -** Module Flags -+ =+fuzzy= Enables fuzzy completion for Helm searches. -+ =+childframe= Causes Helm to display in a floating child frame, above Emacs. -+ =+icons= Enables icons (supports both =all-the-icons= and =treemacs= icons) +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -** Plugins -+ [[https://github.com/emacs-helm/helm][helm]] -+ [[https://github.com/microamp/helm-rg][helm-rg]] -+ [[https://github.com/emacs-jp/helm-c-yasnippet][helm-c-yasnippet]] -+ [[https://github.com/tuhdo/helm-company][helm-company]] -+ [[https://github.com/emacs-helm/helm-describe-modes][helm-describe-modes]] -+ [[https://github.com/bbatsov/helm-projectile][helm-projectile]] -+ [[https://github.com/abo-abo/swiper-helm][helm-swiper]] -+ [[https://github.com/emacs-helm/helm-descbinds][helm-descbinds]] -+ [[https://github.com/PythonNut/helm-flx][helm-flx]]* (=+fuzzy=) -+ [[https://github.com/tumashu/helm-posframe][helm-posframe]]* (=+childframe=) -+ [[https://github.com/emacs-helm/helm-org][helm-org]]* (=:lang org=) -+ [[https://github.com/yyoncho/helm-icons][helm-icons]]* (=+icons=) +This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of +Doom itself, so you should already have it installed. -* Prerequisites -This module has no prerequisites. +Otherwise, Helm provides many commands to interface with a variety of programs +from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These programs are optional +for this module, but must be installed if you intend to use their associated +Helm command or plugin. -* Features -Much like Ivy, Helm is a /large/ framework and as such -covering everything is not in scope, however a number -of Doom-specific features are shown below: +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +Much like [[doom-package:][ivy]] and [[doom-package:][vertico]], [[doom-package:][helm]] is a /large/ framework. Covering all its +features is not within the scope of this module's documentation, so only its +highlights will be covered here. ** Jump-to navigation -Similar to Ivy, this module provides an interface to -navigate within a project using =projectile=: - +Similar to Ivy, this module provides an interface to navigate within a project +using [[doom-package:][projectile]]: | Keybind | Description | |------------------+-------------------------------------| -| =SPC p f=, =SPC SPC= | Jump to file in project | -| =SPC f f=, =SPC .= | Jump to file from current directory | -| =SPC s i= | Jump to symbol in file | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory | +| [[kbd:][SPC s i]] | Jump to symbol in file | ** Project search & replace -This module also provides interacetive text search and replace using ripgrep +This module also provides interactive text search and replace using ripgrep. *** Search - | Keybind | Description | |---------+--------------------------| -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u= +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | + +Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][C-u]] otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files. This module also provides Ex Commands for evil users: - | Ex command | Description | |------------------------+------------------------------------------------------------------| | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) | -The optional `!` is equivalent to the universal argument for the previous +The optional ~!~ is equivalent to the universal argument for the previous commands. *** Replace - These keybindings are available while a search is active: +| Keybind | Description | +|---------+-----------------------------------------------| +| [[kbd:][C-c C-o]] | Open a buffer with your search results | +| [[kbd:][C-c C-e]] | Open a writable buffer of your search results | +| [[kbd:][C-SPC]] | Preview the current candidate | +| [[kbd:][C-RET]] | Open the selected candidate in other-window | -| Keybind | Description | -|-----------+-----------------------------------------------| -| =C-c C-o= | Open a buffer with your search results | -| =C-c C-e= | Open a writable buffer of your search results | -| =C-SPC= | Preview the current candidate | -| =C-RET= | Open the selected candidate in other-window | - -Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed -with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil -users). +Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with +[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). ** In-buffer searching -The =swiper= package provides an interactive buffer search powered by helm. It -can be invoked with: +The [[doom-package:][swiper]] package provides an interactive buffer search powered by helm. It can +be invoked with: +- [[kbd:][SPC s s]] (~swiper-isearch~) +- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~) +- [[kbd:][SPC s b]] (~swiper~) +- ~:sw[iper] [QUERY]~ -+ =SPC s s= (~swiper-isearch~) -+ =SPC s S= (~swiper-isearch-thing-at-point~) -+ =SPC s b= (~swiper~) -+ ~:sw[iper] [QUERY]~ +A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]]. -A wgrep buffer can be opened from swiper with =C-c C-e=. ** Helm integration for various completing commands Helm also has a number of overrides for built-in functionality: *** General | Keybind | Description | |------------+---------------------------| -| =M-x=, =SPC := | Smarter, smex-powered M-x | -| =SPC '= | Resume last ivy session | +| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x | +| [[kbd:][SPC ']] | Resume last ivy session | *** Jump to files, buffers or projects | Keybind | Description | |------------------+---------------------------------------| -| =SPC RET= | Find bookmark | -| =SPC f f=, =SPC .= | Browse from current directory | -| =SPC p f=, =SPC SPC= | Find file in project | -| =SPC f r= | Find recently opened file | -| =SPC p p= | Open another project | -| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | -| =SPC b B=, =SPC <= | Switch to buffer | +| [[kbd:][SPC RET]] | Find bookmark | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project | +| [[kbd:][SPC f r]] | Find recently opened file | +| [[kbd:][SPC p p]] | Open another project | +| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace | +| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer | *** Search | Keybind | Description | |---------+-------------------------------------------| -| =SPC p t= | List all TODO/FIXMEs in project | -| =SPC s b= | Search the current buffer | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -| =SPC s i= | Search for symbol in current buffer | -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s s= | Search the current buffer (incrementally) | +| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project | +| [[kbd:][SPC s b]] | Search the current buffer | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | +| [[kbd:][SPC s i]] | Search for symbol in current buffer | +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s s]] | Search the current buffer (incrementally) | + +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Icons -Icons are now included, and support 2 providers ([[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/Alexander-Miller/treemacs][treemacs]]). -By default, to maintain consistency we use =all-the-icons=; however if you wish -to modify this you can do so using the below snippet: +Icon support is now included, through one of two providers: [[doom-package:][all-the-icons]] and +[[doom-package:][treemacs]]. By default, to maintain consistency we use [[doom-package:][all-the-icons]]; however if +you wish to modify this you can do so using the below snippet: #+begin_src emacs-lisp (after! helm (setq helm-icons-provider 'treemacs)) #+end_src -** Posframe +** TODO Posframe * Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/ido/README.org b/modules/completion/ido/README.org new file mode 100644 index 000000000..e925ebd3f --- /dev/null +++ b/modules/completion/ido/README.org @@ -0,0 +1,58 @@ +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion ido][Issues]] ↖ [[doom-module-source:completion/ido][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :completion ido +#+SUBTITLE: A foil for other search engines +#+CREATED: October 13, 2021 +#+SINCE: 21.12.0 + +* Description :unfold: +Interactive DO things. The completion engine that is /mostly/ built-into Emacs. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][crm-custom]] +- [[doom-package:][flx-ido]] +- [[doom-package:][ido-completing-read+]] +- [[doom-package:][ido-sort-mtime]] +- [[doom-package:][ido-vertical-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* Usage +#+begin_quote +🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Configuration +#+begin_quote +🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* Appendix +#+begin_quote +🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/ido/config.el b/modules/completion/ido/config.el index bced27ee5..5ca00607b 100644 --- a/modules/completion/ido/config.el +++ b/modules/completion/ido/config.el @@ -9,7 +9,6 @@ (use-package! ido :hook (doom-first-input . ido-mode) - :hook (ido-mode . ido-everywhere) :hook (ido-mode . ido-ubiquitous-mode) :preface ;; HACK `ido' is a really old package. It defines `ido-mode' manually and @@ -29,7 +28,8 @@ ido-confirm-unique-completion t ido-case-fold t ido-create-new-buffer 'always - ido-enable-flex-matching t) + ido-enable-flex-matching t + ido-everywhere t) (map! :map (ido-common-completion-map ido-file-completion-map) "C-w" #'ido-delete-backward-word-updir diff --git a/modules/completion/ivy/README.org b/modules/completion/ivy/README.org index 878070e01..b231d2d19 100644 --- a/modules/completion/ivy/README.org +++ b/modules/completion/ivy/README.org @@ -1,28 +1,11 @@ -#+TITLE: completion/ivy -#+DATE: February 13, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion ivy][Issues]] ↖ [[doom-module-source:completion/ivy][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :completion ivy +#+SUBTITLE: Yesterday's lightest search engine +#+CREATED: February 13, 2017 +#+SINCE: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#jump-to-navigation][Jump-to navigation]] - - [[#project-search--replace][Project search & replace]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#ivy-integration-for-various-completing-commands][Ivy integration for various completing commands]] - - [[#general][General]] - - [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]] - - [[#search][Search]] -- [[#configuration][Configuration]] - - [[#enable-fuzzynon-fuzzy-search-for-specific-commands][Enable fuzzy/non-fuzzy search for specific commands]] - - [[#change-the-position-of-the-ivy-childframe][Change the position of the ivy childframe]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module provides Ivy integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. @@ -31,63 +14,87 @@ I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter, simpler and faster in many cases. #+end_quote -** Module Flags -+ =+fuzzy= Enables fuzzy completion for Ivy searches. -+ =+prescient= Enables prescient filtering and sorting for Ivy searches. -+ =+childframe= Causes Ivy to display in a floating child frame, above Emacs. -+ =+icons= Enables file icons for switch-{buffer,project}/find-file counsel - commands. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/abo-abo/swiper][ivy]] -+ [[https://github.com/abo-abo/swiper][counsel]] -+ [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]] -+ [[https://github.com/abo-abo/swiper][swiper]] -+ [[https://github.com/abo-abo/swiper][ivy-hydra]] -+ [[https://github.com/yevgnen/ivy-rich][ivy-rich]] -+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] -+ [[https://github.com/DarwinAwardWinner/amx][amx]] -+ [[https://github.com/lewang/flx][flx]]* (=+fuzzy=) -+ [[https://github.com/raxod502/prescient.el][prescient]]* (=+prescient=) -+ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=) -+ [[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]]* (=+icons=) +** Module flags +- +childframe :: + Display Ivy windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires + GUI Emacs.* +- +fuzzy :: + Enable fuzzy completion for Ivy searches. +- +icons :: + Enable file icons for switch-{buffer,project}/find-file commands. +- +prescient :: + Enable prescient filtering and sorting for Ivy searches. + +** Packages +- [[doom-package:][all-the-icons-ivy]]* if [[doom-module:][+icons]] +- [[doom-package:][amx]] +- [[doom-package:][counsel]] +- [[doom-package:][counsel-projectile]] +- [[doom-package:][flx]]* if [[doom-module:][+fuzzy]] +- [[doom-package:][ivy]] +- [[doom-package:][ivy-hydra]] +- [[doom-package:][ivy-posframe]]* if [[doom-module:][+childframe]] +- [[doom-package:][ivy-rich]] +- [[doom-package:][prescient]]* if [[doom-module:][+prescient]] +- [[doom-package:][swiper]] +- [[doom-package:][wgrep]] ** Hacks -+ Functions with ivy/counsel equivalents have been globally remapped (like +- 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 +- ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex command) -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -Ivy and its ilk are large plugins. Covering everything about them is outside of -this documentation's scope, so only Doom-specific Ivy features are listed here: +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of +Doom itself, so you should already have it installed. + +Otherwise, Counsel (an Ivy plugin) provides many commands to interface with a +variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These +programs are optional for this module, but must be installed if you intend to +use their associated Helm command or plugin. + +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +[[doom-package:][ivy]] is a /large/ framework for completing things. Covering all its features is +not within the scope of this module's documentation, so only its highlights will +be covered here. ** Jump-to navigation Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's -Command-T, this module provides similar functionality by bringing ~projectile~ -and ~ivy~ together. +Command-T, this module provides similar functionality by bringing [[doom-package:][projectile]] and +[[doom-package:][ivy]] together. https://assets.doomemacs.org/completion/ivy/projectile.png -| Keybind | Description | -|----------------------+-------------------------------------| -| =SPC p f=, =SPC SPC= | Jump to file in project | -| =SPC f f=, =SPC .= | Jump to file from current directory | -| =SPC s i= | Jump to symbol in file | +| Keybind | Description | +|------------------+-------------------------------------| +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory | +| [[kbd:][SPC s i]] | Jump to symbol in file | ** Project search & replace This module provides interactive text search and replace using ripgrep. -| Keybind | Description | -|-----------+--------------------------| -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | https://assets.doomemacs.org/completion/ivy/search.png @@ -96,7 +103,6 @@ otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files. This module also provides Ex Commands for evil users: - | Ex command | Description | |------------------------+------------------------------------------------------------------| | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | @@ -108,65 +114,79 @@ commands. ----- These keybindings are available while a search is active: +| Keybind | Description | +|---------+-----------------------------------------------| +| [[kbd:][C-c C-o]] | Open a buffer with your search results | +| [[kbd:][C-c C-e]] | Open a writable buffer of your search results | +| [[kbd:][C-SPC]] | Preview the current candidate | +| [[kbd:][C-RET]] | Open the selected candidate in other-window | -| Keybind | Description | -|-----------+-----------------------------------------------| -| =C-c C-o= | Open a buffer with your search results | -| =C-c C-e= | Open a writable buffer of your search results | -| =C-SPC= | Preview the current candidate | -| =C-RET= | Open the selected candidate in other-window | - -Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed -with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil -users). +Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with +[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). https://assets.doomemacs.org/completion/ivy/search-replace.png ** In-buffer searching -The =swiper= package provides an interactive buffer search powered by ivy. It +The [[doom-package:][swiper]] package provides an interactive buffer search powered by ivy. It can be invoked with: -+ =SPC s s= (~swiper-isearch~) -+ =SPC s S= (~swiper-isearch-thing-at-point~) -+ =SPC s b= (~swiper~) -+ ~:sw[iper] [QUERY]~ +- [[kbd:][SPC s s]] (~swiper-isearch~) +- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~) +- [[kbd:][SPC s b]] (~swiper~) +- ~:sw[iper] [QUERY]~ https://assets.doomemacs.org/completion/ivy/swiper.png -A wgrep buffer can be opened from swiper with =C-c C-e=. +A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]]. ** Ivy integration for various completing commands *** General -| Keybind | Description | -|----------------+---------------------------| -| =M-x=, =SPC := | Smarter, smex-powered M-x | -| =SPC '= | Resume last ivy session | +| Keybind | Description | +|------------+---------------------------| +| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x | +| [[kbd:][SPC ']] | Resume last ivy session | *** Jump to files, buffers or projects -| Keybind | Description | -|----------------------+---------------------------------------| -| =SPC RET= | Find bookmark | -| =SPC f f=, =SPC .= | Browse from current directory | -| =SPC p f=, =SPC SPC= | Find file in project | -| =SPC f r= | Find recently opened file | -| =SPC p p= | Open another project | -| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | -| =SPC b B=, =SPC <= | Switch to buffer | +| Keybind | Description | +|------------------+---------------------------------------| +| [[kbd:][SPC RET]] | Find bookmark | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project | +| [[kbd:][SPC f r]] | Find recently opened file | +| [[kbd:][SPC p p]] | Open another project | +| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace | +| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer | *** Search -| Keybind | Description | -|-----------+-------------------------------------------| -| =SPC p t= | List all TODO/FIXMEs in project | -| =SPC s b= | Search the current buffer | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -| =SPC s i= | Search for symbol in current buffer | -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s s= | Search the current buffer (incrementally) | +| Keybind | Description | +|---------+-------------------------------------------| +| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project | +| [[kbd:][SPC s b]] | Search the current buffer | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | +| [[kbd:][SPC s i]] | Search for symbol in current buffer | +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s s]] | Search the current buffer (incrementally) | + +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** TODO Enable fuzzy/non-fuzzy search for specific commands ** TODO Change the position of the ivy childframe * TODO Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/vertico/README.org b/modules/completion/vertico/README.org index 31fa9f611..dc7a731e6 100644 --- a/modules/completion/vertico/README.org +++ b/modules/completion/vertico/README.org @@ -1,73 +1,67 @@ -#+TITLE: completion/vertico -#+DATE: July 25, 2021 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages +← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion vertico][Issues]] ↖ [[doom-module-source:completion/vertico][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] +-------------------------------------------------------------------------------- +#+TITLE: :completion vertico +#+SUBTITLE: Tomorrow's search engine +#+CREATED: August 17, 2021 +#+SINCE: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#vertico-keybindings][Vertico keybindings]] - - [[#jump-to-navigation][Jump-to navigation]] - - [[#project-search--replace][Project search & replace]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#vertico-integration-for-various-completing-commands][Vertico integration for various completing commands]] - - [[#general][General]] - - [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]] - - [[#search][Search]] - - [[#file-path-completion][File Path Completion]] - - [[#consult][Consult]] - - [[#multiple-candidate-search][Multiple candidate search]] - - [[#async-search-commands][Async search commands]] - - [[#marginalia][Marginalia]] - - [[#orderless-filtering][Orderless filtering]] -- [[#configuration][Configuration]] - - [[#vertico][Vertico]] - - [[#consult-1][Consult]] - - [[#marginalia-1][Marginalia]] - - [[#embark][Embark]] - -* Description +* Description :unfold: This module enhances the Emacs search and completion experience, and also provides a united interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. It does this with several modular packages focused on enhancing the built-in ~completing-read~ interface, rather than replacing it with a parallel ecosystem -like =ivy= and =helm= do. The primary packages are: +like [[doom-package:][ivy]] and [[doom-package:][helm]] do. The primary packages are: -+ Vertico, which provides the vertical completion user interface -+ Consult, which provides a suite of useful commands using ~completing-read~ -+ Embark, which provides a set of minibuffer actions -+ Marginalia, which provides annotations to completion candidates -+ Orderless, which provides better filtering methods +- Vertico, which provides the vertical completion user interface +- Consult, which provides a suite of useful commands using ~completing-read~ +- Embark, which provides a set of minibuffer actions +- Marginalia, which provides annotations to completion candidates +- Orderless, which provides better filtering methods ** Maintainers -+ @iyefrat +- [[doom-user:][@iyefrat]] -** Module Flags -+ =+icons= Adds icons to =file= and =buffer= category completion selections. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/minad/vertico][vertico]] -+ [[https://github.com/minad/consult][consult]] -+ [[https://github.com/oantolin/embark/][embark]] -+ [[https://github.com/oantolin/embark/][embark-consult]] -+ [[https://github.com/minad/marginalia][marginalia]] -+ [[https://github.com/oantolin/orderless][orderless]] -+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] -+ [[https://github.com/minad/consult/][consult-flycheck]] (=:checkers syntax=) -+ [[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]] (=+icons=) +** Module flags +- +icons :: + Add icons to =file= and =buffer= category completion selections. -* Prerequisites -Some of the advanced filtering features in async =consult= commands require -=grep= and =ripgrep= to be built with support for [[https://www.pcre.org/][PCRE]] lookahead, see [[#async-search-commands][Async -search commands]] for more information. You can check if this is true for your -machine by running ~doom doctor~. +** Packages +- [[doom-package:][all-the-icons-completion]] if [[doom-module:][+icons]] +- [[doom-package:][consult]] +- [[doom-package:][consult-flycheck]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][embark]] +- [[doom-package:][embark-consult]] +- [[doom-package:][marginalia]] +- [[doom-package:][orderless]] +- [[doom-package:][vertico]] +- [[doom-package:][wgrep]] -* Features +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]] (built with [[https://www.pcre.org/][PCRE]] support; run ~$ +doom doctor~ to determine if your build meets this requirement), which is a hard +dependency of Doom itself, so you should already have it installed. + +Otherwise, Consult (a plugin this module installs) provides many commands to +interface with a variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ +more. These programs are optional for this module, but must be installed if you +intend to use their associated Helm command or plugin. + +* TODO Usage +#+begin_quote + 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote The packages in this module modify and use the built-in ~completing-read~ function, which is used by any function that requires completion. Due to this @@ -79,117 +73,116 @@ Doom-specific additions: When in an active Vertico completion session, the following doom added keybindings are available: -| Keybind | Description | -|-----------------------+----------------------------------------------------| -| =C-k= | (evil) Go to previous candidate | -| =C-j= | (evil) Go to next candidate | -| =C-M-k= | (evil) Go to previous group | -| =C-M-j= | (evil) Go to next group | -| =C-;= or = a= | Open an ~embark-act~ menu to chose a useful action | -| =C-c C-;= | export the current candidate list to a buffer | -| =C-SPC= | Preview the current candidate | +| Keybind | Description | +|--------------+--------------------------------------------------| +| [[kbd:][C-k]] | (evil) Go to previous candidate | +| [[kbd:][C-j]] | (evil) Go to next candidate | +| [[kbd:][C-M-k]] | (evil) Go to previous group | +| [[kbd:][C-M-j]] | (evil) Go to next group | +| [[kbd:][C-;]] or [[kbd:][ a]] | Open an ~embark-act~ menu to chose a useful action | +| [[kbd:][C-c C-;]] | export the current candidate list to a buffer | +| [[kbd:][C-SPC]] | Preview the current candidate | ~embark-act~ will prompt you with a =which-key= menu with useful commands on the selected candidate or candidate list, depending on the completion category. Note -that you can press =C-h= instead of choosing a command to filter through the +that you can press [[kbd:][C-h]] instead of choosing a command to filter through the options with a Vertico buffer, that also has slightly more detailed descriptions due to Marginalia annotations. ** Jump-to navigation This module provides an interface to navigate within a project using -=projectile=: +[[doom-package:][projectile]]: https://assets.doomemacs.org/completion/vertico/projectile.png -| Keybind | Description | -|----------------------+-------------------------------------| -| =SPC p f=, =SPC SPC= | Jump to file in project | -| =SPC f f=, =SPC .= | Jump to file from current directory | -| =SPC s i= | Jump to symbol in file | +| Keybind | Description | +|------------------+-------------------------------------| +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory | +| [[kbd:][SPC s i]] | Jump to symbol in file | ** Project search & replace This module provides interactive text search and replace using ripgrep. -| Keybind | Description | -|-----------+--------------------------| -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][ s p]] | Search project | +| [[kbd:][ s P]] | Search another project | +| [[kbd:][ s d]] | Search this directory | +| [[kbd:][ s D]] | Search another directory | https://assets.doomemacs.org/completion/vertico/search.png -Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u= +Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][C-u]] otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files. This module also provides Ex Commands for evil users: - -| Ex command | Description | -|------------------------+------------------------------------------------------------------| +| Ex command | Description | +|----------------------+----------------------------------------------------------------| | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) | -The optional `!` is equivalent to the universal argument for the previous +The optional ~!~ is equivalent to the universal argument for the previous commands. ----- On top of the usual Vertico keybindings, search commands also offer support for -exporting the current candidate list to an editable buffer =C-c C-e=. After -editing the changes can be committed with =C-c C-c= and aborted with =C-c C-k= -(alternatively =ZZ= and =ZQ=, for evil users). It uses =wgrep= for grep -searches, =wdired= for file searches, and =occur= for buffer searches. +exporting the current candidate list to an editable buffer [[kbd:][C-c C-e]]. After +editing the changes can be committed with [[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] +(alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). It uses [[doom-package:][wgrep]] for grep searches, +[[doom-package:][wdired]] for file searches, and =occur= for buffer searches. https://assets.doomemacs.org/completion/vertico/search-replace.png ** In-buffer searching This module provides some in buffer searching bindings: -+ =SPC s s= (~isearch~) -+ =SPC s S= (~+vertico/search-symbol-at-point~ via ~consult-line~) -+ =SPC s b= (~consult-line~) +- [[kbd:][SPC s s]] (~isearch~) +- [[kbd:][SPC s S]] (~+vertico/search-symbol-at-point~ via ~consult-line~) +- [[kbd:][SPC s b]] (~consult-line~) https://assets.doomemacs.org/completion/vertico/buffer-search.png -An ~occur-edit~ buffer can be opened from ~consult-line~ with =C-c C-e=. +An ~occur-edit~ buffer can be opened from ~consult-line~ with [[kbd:][C-c C-e]]. ** Vertico integration for various completing commands *** General -| Keybind | Description | -|----------------+-----------------------------| -| =M-x=, =SPC := | Enhanced M-x | -| =SPC '= | Resume last Vertico session | +| Keybind | Description | +|------------+-----------------------------| +| [[kbd:][M-x]], [[kbd:][SPC :]] | Enhanced M-x | +| [[kbd:][SPC ']] | Resume last Vertico session | *** Jump to files, buffers or projects -| Keybind | Description | -|----------------------+---------------------------------------| -| =SPC RET= | Find bookmark | -| =SPC f f=, =SPC .= | Browse from current directory | -| =SPC p f=, =SPC SPC= | Find file in project | -| =SPC f r= | Find recently opened file | -| =SPC p p= | Open another project | -| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | -| =SPC b B=, =SPC <= | Switch to buffer | +| Keybind | Description | +|------------------+---------------------------------------| +| [[kbd:][SPC RET]] | Find bookmark | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project | +| [[kbd:][SPC f r]] | Find recently opened file | +| [[kbd:][SPC p p]] | Open another project | +| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace | +| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer | -=SPC b b= and =SPC ,= support changing the workspace you're selecting a buffer from +[[kbd:][SPC b b]] and [[kbd:][SPC ,]] support changing the workspace you're selecting a buffer from via [[https://github.com/minad/consult#narrowing-and-grouping][Consult narrowing]], e.g. if you're on the first workspace, you can switch to -selecting a buffer from the third workspace by typing =3 SPC= into the prompt, -or the last workspace by typing =0 SPC=. +selecting a buffer from the third workspace by typing [[kbd:][3 SPC]] into the prompt, or +the last workspace by typing [[kbd:][0 SPC]]. -=SPC f f= and =SPC .= support exporting to a =wdired= buffer using =C-c C-e=. +[[kbd:][SPC f f]] and [[kbd:][SPC .]] support exporting to a [[kbd:][wdired]] buffer using [[kbd:][C-c C-e]]. *** Search -| Keybind | Description | -|-----------+-------------------------------------------| -| =SPC p t= | List all TODO/FIXMEs in project | -| =SPC s b= | Search the current buffer | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -| =SPC s i= | Search for symbol in current buffer | -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s s= | Search the current buffer (incrementally) | +| Keybind | Description | +|---------+-------------------------------------------| +| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project | +| [[kbd:][SPC s b]] | Search the current buffer | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | +| [[kbd:][SPC s i]] | Search for symbol in current buffer | +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s s]] | Search the current buffer (incrementally) | *** File Path Completion Note that Emacs allows you to switch directories with shadow paths, for example @@ -205,17 +198,20 @@ This module modifies the default keybindings used in ~consult-completing-read-multiple~: | Keybind | Description | |---------+-------------------------------------------------------------| -| =TAB= | Select or deselect current candidate | -| =RET= | Enters selected candidates (also toggles current candidate) | +| [[kbd:][TAB]] | Select or deselect current candidate | +| [[kbd:][RET]] | Enters selected candidates (also toggles current candidate) | *** Async search commands +:PROPERTIES: +:ID: 4ab16bf0-f9e8-4798-8632-ee7b13d2291e +:END: Consult async commands (e.g. ~consult-ripgrep~) will have a preceding separator -character (usually =#=) before the search input. This is known as the =perl= +character (usually ~#~) before the search input. This is known as the =perl= splitting style. Input typed after the separator will be fed to the async command until you type a second seperator, afterwhich the candidate list will be -filtered with Emacs instead (and can be filtered using =orderless=, for -example). The specific seperator character can be changed by editing it, and -might be different if the initial input already contains =#=. +filtered with Emacs instead (and can be filtered using [[doom-package:][orderless]], for example). +The specific seperator character can be changed by editing it, and might be +different if the initial input already contains =#=. Note that grep-like async commands translate the input (between the first and second =#=) to an Orderless-light expression: space separated inputs are all @@ -228,11 +224,11 @@ For more information [[https://github.com/minad/consult#asynchronous-search][see ** Marginalia | Keybind | Description | |---------+---------------------------------| -| =M-A= | Cycle between annotation levels | +| [[kbd:][M-A]] | Cycle between annotation levels | -Marginalia annotations for symbols (e.g. =SPC h f= and =SPC h v=) come with -extra information the nature of the symbol. For the meaning of the annotations -see ~marginalia--symbol-class~. +Marginalia annotations for symbols (e.g. [[kbd:][SPC h f]] and [[kbd:][SPC h v]]) come with extra +information the nature of the symbol. For the meaning of the annotations see +~marginalia--symbol-class~. ** Orderless filtering When using orderless to filter through candidates, the default behaviour is for @@ -245,40 +241,62 @@ first matched candidate as input. Filtering further is instead achieved by pressing space and entering another input. In essence, when trying to match =foobar.org=, instead of option 1., use option 2.: -1. (BAD) Enter =foo TAB=, completes to =foobar.=, enter =org RET= -2. (GOOD) Enter =foo SPC org RET= +1. (BAD) Enter ~foo TAB~, completes to =foobar.=, enter ~org RET~ +2. (GOOD) Enter ~foo SPC org RET~ -Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more finegrained filtering, which +Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more fine-grained filtering, which you can use to further specify each space separated input in the following ways: -| Input | Description | -|------------------+----------------------------------------------| -| =!foo= | match without literal input =foo= | -| =%foo= or =foo%= | perform ~char-fold-to-regexp~ on input =foo= | -| =`foo= or =foo`= | match input =foo= as an initialism | -| ==foo= or =foo== | match only with literal input =foo= | -| =~foo= or =foo~= | match input =foo= with fuzzy/flex matching | +| Input | Description | +|--------------+------------------------------------------| +| ~!foo~ | match without literal input =foo= | +| ~%foo~ or ~foo%~ | perform ~char-fold-to-regexp~ on input =foo= | +| ~`foo~ or ~foo`~ | match input =foo= as an initialism | +| ~=foo~ or ~foo=~ | match only with literal input =foo= | +| ~~foo~ or ~foo~~ | match input =foo= with fuzzy/flex matching | + +* TODO Configuration +#+begin_quote + 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +If you want to further configure this module, here are some good places to +start: -* Configuration -If you want to further configure this module, here are some good places to start: ** Vertico Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface + ** Consult Much of the behaviour of Consult commands can be changed with ~consult-customize~. The =vertico= module already does this, if you want to override the module's modifications, do: #+begin_src emacs-lisp (setq consult--read-config nil) -(consult-customize -;... -) +(consult-customize ...) #+end_src -If you are changing the preview key (set to =C-SPC=), remember to change the + +If you are changing the preview key (set to [[kbd:][C-SPC]]), remember to change the binding on ~vertico-map~ as well, as the binding there gets previews to work to an extent on non-consult commands as well. + ** Marginalia You can add more Marginalia annotation levels and change the existing ones by - editing ~marginalia-annotator-registry~ +editing ~marginalia-annotator-registry~ + ** Embark You can change the available commands in Embark for category ~$cat~ by editing - ~embark-$cat-map~, and even add new categories. Note that you add categories - by defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them. +~embark-$cat-map~, and even add new categories. Note that you add categories by +defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* TODO Appendix +#+begin_quote + 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote