diff --git a/modules/completion/vertico/README.org b/modules/completion/vertico/README.org index cfc81f358..013d90660 100644 --- a/modules/completion/vertico/README.org +++ b/modules/completion/vertico/README.org @@ -3,39 +3,55 @@ #+SINCE: v3.0.0 #+STARTUP: inlineimages -* Table of Contents :TOC_2:noexport: +* 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]] + - [[#marginalia][Marginalia]] - [[#orderless-filtering][Orderless filtering]] +- [[#configuration][Configuration]] * Description -This module provides Vertico integration for a variety of Emacs commands, as -well as a unified interface for project search and replace, powered by ripgrep. +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]]. -#+begin_quote -TODO -#+end_quote +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: + ++ 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 +This module has no dedicated maintainers. ** Module Flags -+ ~+icons~ Adds icons to ~file~ and ~buffer~ category completion selections. ++ =+icons= Adds icons to =file= and =buffer= category completion selections. ** 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~) ++ [[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=) * Prerequisites This module has no prerequisites. @@ -48,6 +64,28 @@ the full scope of these packages is too large to cover here and you are encouraged to go and read their excellent documentation. We will detail Doom-specific additions: +** Vertico keybindings +When in an active Vertico completion session, the following doom added +keybindings are available: + +| Keybind | Description | +|-----------------------+----------------------------------------------------| +| =C-p= | Go to previous candidate | +| =C-n= | Go to next candidate | +| =C-k= | (evil) Go to previous candidate | +| =C-j= | (evil) Go to next candidate | +| =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 | +| =C-M-k= | (evil) Go to previous candidate and preview. | +| =C-M-j= | (evil) Go to next candidate and preview. | + +~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 +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=: @@ -88,21 +126,11 @@ commands. ----- -These keybindings are available while a search is active: - -| Keybind | Description | -|---------------------+----------------------------------------------------| -| =C-;=, = a= | Open an ~embark-act~ menu to chose a useful action | -| =C-c C-;= | 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-M-j= | Scroll down and preview. | -| =C-M-k= | Scroll up and preview. | -| =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). +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. https://assets.doomemacs.org/completion/vertico/search-replace.png @@ -154,6 +182,11 @@ or the last workspace by typing =0 SPC=. | =SPC s P= | Search another project | | =SPC s s= | Search the current buffer (incrementally) | +** Marginalia +| Keybind | Description | +|---------+---------------------------------| +| =M-A= | Cycle between annotation levels | + ** Orderless filtering When using orderless to filter through candidates, the default behaviour is for each space separated input to match the candidate as a regular expression or @@ -176,3 +209,13 @@ you can use to further specify each space separated input in the following ways: | =`bar= or =bar`= | match input =bar= as an initialism | | ==baz= or =baz== | match only with literal input =baz= | | =~qux= or =qux~= | match input =qux= with fuzzy/flex matching | + +* Configuration +If you want to further configure this module, here are some good places to start: + ++ Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface ++ You can add more Marginalia annotation levels and change the existing ones by + editing ~marginalia-annotator-registry~ ++ 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. diff --git a/modules/completion/vertico/TODO.org b/modules/completion/vertico/TODO.org index bfdec7c0c..ca065bcfb 100644 --- a/modules/completion/vertico/TODO.org +++ b/modules/completion/vertico/TODO.org @@ -35,15 +35,13 @@ case for why this should be an exception: installed independently, so if you find it sufficiently useful you could also have a stripped down version of the config in doom core that is just used for on-buffer actions. +*** We also might want to add keybinidngs for =embark-dwim= ** TODO =SPC s s= and =SPC s S= ~:sw~ ? There isn't really a vertico/consult analogue to ~swiper-isearch~, ~consult-isearch~ does something else (give you previously used isearch search terms). Bound to regular isearch for now. ** TODO =SPC s B= Vertico/Consult don't have a ~swiper-all~ analogue either. Unbound for now. -** TODO Orderless style dispatchers -Currently the =!= style dispatcher is only as a prefix, due to the abundance of -=!= final macros. In my opinion this is useful enough to break consistency. ** TODO =C-c C-e= On ~consult-line~ this opens a ~occur-edit~ buffer, which is a more natural fit but breaks slightly from the =C-c C-e= = =wgrep= convention. @@ -53,12 +51,51 @@ I like having them around but I can always just add them to my private config. ** TODO Annotation Customization Do we want to have the annotations be more like ivy? e.g. - Have a project column in the buffer annotations and a relative path? This has - some overlap with project narrowing =SPC b B p SPC. + some overlap with project narrowing =SPC b B p SPC=. - Mark the modified/remote status of the buffer with color, on top of the modification column? - Change colors in general? +** TODO Orderless +*** TODO Style dispatchers + Currently the =!= style dispatcher is only as a prefix, due to the abundance of + =!= final macros. In my opinion this is useful enough to break consistency. +*** TODO Completion Style on file paths +Currently we have the following completion style override for files: +#+begin_src emacs-lisp +(setq completion-category-overrides '((file (styles . (orderless partial-completion))))) +#+end_src +This means that =parital-completion= matches (basically completing word +prefixes + globbing) only get considered if there are no =orderless= matches. I +find this to be the useful order, since I only really want =partial-completion= +for the globbing, but it does mean that you lose the ability to type the first +few letters of a file and only get the files that start with that, since you get +broader orderless matching. Ivy doesn't have this distinction with prescient on, +but does seem to only show hidden files only after there are no visible ones +left, which we don't have here. -* PROJ HACKs to be addressed +This also relates to the [[https://github.com/minad/vertico#tramp-hostname-completion][recommended settings in the vertico readme]] for remote +hostname completion somewhat. It's hard for me to figure out what's best here +because I don't have any remotes to try this out on. +*** TODO Initialisms by default/ +Do we want to use =orderless+initialism= by default for some of the completion +categories? see [[https://github.com/hlissner/doom-emacs/pull/4664#discussion_r667368998 +][here]] +** TODO Decide what Vertico extensions to use +Currently we only use =vertico-repeat=, and after the next bump I'll replace +~+vertico/backward-updir~ with the =vertico-directory= implementation. Do we +want to use any other ones or leave that to users? +** TODO Decide what to do with ~embark-package-map~ +** TODO =SPC b B= currently displays recent files and bookmarks by default +We can have it only display buffers by setting an initial narrowing +** TODO Company completion style +Currently we advise ~company-capf--candidates~ to try the default emacs +completion styles before orderless, since trying orderless first leads to a +bunch of junk candidates. We could let the company completion style here be a +variable for mildly easy customization, and we could also use orderless but use +a custom sorting function like ~vertico-sort-length-alpha~ which has decent +results ([[https://github.com/hlissner/doom-emacs/pull/4664#discussion_r668897763][see here]]). + +* PROJ HACKs that need looking over ** TODO ~fboundp~ issues Even if the =ivy= module isn't loaded, it's packages can still get loaded by other means, such as =lispy= requiring =counsel=. This means that the ~fboundp~ @@ -68,29 +105,33 @@ first, which is what we do for now. Without [[file:~/.emacs.d/modules/ui/workspaces/config.el::;; HACK?? needs review][this]] change new projects don't get opened in a new tab, but the exact working of this whole set up are a bit opaque to me. -* PROJ Review blocking Issues -** TODO Embark export window buffer switching logic -*** DONE ~grep~ -The clicking links exported grep buffers used to open in a new window, but now - open in another window. Caused by the ~set-popup-rule!~ entries for the embark - export/collect buffers. These don't seem to serve much of a purpose at this - point so they have been removed. -*** TODO Open upstream Embark issue for ~bookmark~ and ~file~ -~bookmark~ or ~file~ export buffers open the links in the same window rather than -the other one. This can be reproduces on emacs -Q. -This is due to orderless adding a bunch of other matches. +* PROJ Things I'd like help with +** TODO Fix ~(defadvice! +orderless-match-with-one-face..~ lexical error +[[https://github.com/oantolin/orderless/issues/41][Probably caused by some doomism]] +** TODO Embark Export/Correct popup logic +Currently when e.g. exporting a ~consult-grep~ search to a grep buffer, it just +gets exported to a new window without any special configuration with +~set-popup-rule!~. This is because using ~set-popup-rule!~ causes the links in +the grep buffer to be opened in a new window rather than the other window, which +is undesirable. However, the default window opening logic leads to the exported +buffer being opened in a right split if the emacs frame is wide, which is also +undesirable. I have not been able to figure out what about the doom popup +mechanism is causing this, I don't think it's something in ~set-popup-rule!~ +directly, but something deeper in the =:ui popup= -* PROJ Review non-blocking Issues + +* PROJ Things to do before the merge ** TODO Profile vertico =SPC /= vs ivy =SPC /= Check if there are other places where optimisations can be made. Perhaps the -~command-input-async~ variables can tolorate lower values. -** TODO ~(defadvice! +orderless-match-with-one-face..~ causes lexical error -Probably caused by some doomism - -https://github.com/oantolin/orderless/issues/41 +~command-input-async~ variables can tolerate lower values. +** TODO Better Marginalia annotations for Projectile commands (maybe upstream) +** TODO after the next bump, replace ~+vertico/backward-updir~ with ~vertico-directory~ version +** TODO bump =bibtex-actions= +** TODO Fix the duplicate candidate issue +[[https://github.com/minad/vertico/issues/69][See here.]] If this doesn't get fixed upstream by the time of the merge we should +add an override for ~read-library-name~ at least. * PROJ Extra credit -** ~vertico-repeat~ doesn't reselect the candidate ** TODO =bibtex-actions= improvements? Currently =SPC n b= is bound to a function, but =bibtex-actions= doesn't have a main dispatch function like =ivy-bibtex=, rather it has a bunch of different