emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

vertico: Improve README and update TODO...

Browse source 
- Add basic configuration instructions
- Add Vertico keybindings
- Improve =C-c C-e= documentation
- Prepare TODO for PR review
This commit is contained in:
Itai Y. Efrat 2021-07-11 20:01:27 +03:00
parent a0eb4e9b65
commit 34f8e1fdec
2 changed files with 138 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

105
modules/completion/vertico/README.org
View file

@ -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 =<leader> 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-;=, =<leader> 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.

87
modules/completion/vertico/TODO.org
View file

@ -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