doomemacs/modules/completion/vertico/TODO.org

• PROJ Design Decisions
  • Bind consult-lsp-diagnostics to something?
  • Finalize embark-act keybindings
    • C-;
    • Alternative chord: C-,
    • <leader> a
    • We also might want to add keybinidngs for embark-dwim
  • SPC s s and SPC s S :sw ?
  • SPC s B
  • C-c C-e
  • Keep or discard C-M-j and C-M-k
  • Annotation Customization
  • Orderless
    • Style dispatchers
    • Completion Style on file paths
    • Initialisms by default/
  • Decide what Vertico extensions to use
  • Decide what to do with embark-package-map
  • SPC b B currently displays recent files and bookmarks by default
  • Company completion style
• PROJ HACKs that need looking over
  • fboundp issues
  • projectile-switch-project-action definition
• PROJ Things I'd like help with
  • Fix (defadvice! +orderless-match-with-one-face.. lexical error
  • Embark Export/Correct popup logic
• PROJ Things to do before the merge
  • Profile vertico SPC / vs ivy SPC /
  • Better Marginalia annotations for Projectile commands (maybe upstream)
  • after the next bump, replace +vertico/backward-updir with vertico-directory version
  • bump bibtex-actions
  • Fix the duplicate candidate issue
• PROJ Extra credit
  • bibtex-actions improvements?
  • Buffer switching
  • Ivy Parity
    • C-RET on minibuffer?
    • pass module
    • +ivy/jump-list analogue
    • WAIT lookup module
    • WAIT taskrunner module

PROJ Design Decisions

TODO Bind consult-lsp-diagnostics to something?

TODO Finalize embark-act keybindings

They are currently set to C-; and <leader> a. The motivation for this is as follows:

C-;

Least intrusive key-chord type binding I could find. Doesn't interfere with other keybindings for the most part (unlike C-o which clashes for in minibuffer evil-want-minibuffer users and regular buffer evil users), with the exception of:

• C-; is bound to flyspell-auto-correct-previous-word. via the built in flyspell map.
• C-; is bound to +company/complete in the vanilla emacs bindings.

We could also just bind it in the minibuffer if we do end up going with the leader key.

Alternative chord: C-,

Still has some overlaps, but perhaps less important:

• flyspell-goto-next-error
• org-cycle-agenda-files has redundancy in C-' anyway.

It is however less convenient than C-;

<leader> a

Even though top level module dependant bindings are frowned upon, here is my case for why this should be an exception:

• It provide a useful shortcut for a bunch of commands relevant to the symbol at point, and seems to be better at this than built in stuff, e.g. doing <leader> f D to delete a file in eshell doesn't work, but embark recognises that it's a file, so <leader> a d does.
• other than helping with discoverability for stuff this also allows for commands for things that are too niche for top level bindings, such as actions on package! statements and recipes or urls.
• vertico is slated to become the default completion module, which makes this less of an inconsistency, but I'm not sure about the performance slowdown in map! since that seems to be one of the main concerns.
• embark like most packages in the vertico cinematic universe can be 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 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.

TODO Keep or discard C-M-j and C-M-k

Scroll up and down while previewing. Essentially shortcuts for C-(j|k) C-SPC. 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.
• 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:

(setq completion-category-overrides '((file (styles . (orderless partial-completion)))))

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.

This also relates to the 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 (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 logic here (and formerly here) won't work unless the vertico option is checked first, which is what we do for now.

TODO projectile-switch-project-action definition

Without 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 Things I'd like help with

TODO Fix (defadvice! +orderless-match-with-one-face.. lexical error

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

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

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 ones. Binding the bibtex-actions-map there would probably be better, but there are nontrivial loading order shenanigans happening that make that not straightforward.

TODO Buffer switching

• SPC b b should switch workspace after choosing a buffer from a different one
• Universal argument for opening buffer in another window?

TODO Ivy Parity

TODO C-RET on minibuffer?

TODO pass module

TODO +ivy/jump-list analogue

WAIT lookup module

• dash-docs backend (needs to be created)
• +lookup--online.. functionality (needs a consult analogue of counsel-search)

WAIT taskrunner module

in all likelihood requires writing consult-taskrunner.