forked from minad/vertico
-
-
Notifications
You must be signed in to change notification settings - Fork 0
/
vertico.texi
215 lines (181 loc) · 7.56 KB
/
vertico.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename vertico.info
@settitle vertico.el - VERTical Interactive COmpletion
@documentencoding UTF-8
@documentlanguage en
@c %**end of header
@dircategory Emacs
@direntry
* Vertico: (vertico). VERTical Interactive COmpletion.
@end direntry
@finalout
@titlepage
@title vertico.el - VERTical Interactive COmpletion
@author Daniel Mendler
@end titlepage
@contents
@ifnottex
@node Top
@top vertico.el - VERTical Interactive COmpletion
@end ifnottex
@menu
* Introduction::
* Features::
* Configuration::
* Keymap::
* Complementary packages::
* Alternatives::
@end menu
@node Introduction
@chapter Introduction
This package provides a minimalistic vertical completion UI, which is based on
the default completion system. By reusing the default system, Vertico achieves
full compatibility with built-in Emacs commands and completion tables. Vertico
is pretty bare-bone and only provides a minimal set of commands. The code base
is less than 500 lines of code. Additional optional enhancements can be provided
externally by complementary packages.
@uref{https://github.com/minad/vertico/blob/main/screenshot.svg?raw=true}
@node Features
@chapter Features
@itemize
@item
Vertical display with arrow key navigation
@item
Shows the index of the current candidate and the total number of candidates
@item
The current candidate is inserted with @samp{TAB} and selected with @samp{RET}
@item
Non-existing candidates are entered by moving the point to the prompt line
@item
Candidates are sorted by history, string length and alphabetically
@item
Long candidates with newlines are formatted to take up less space
@item
Support for @code{annotation-function}, @code{affixation-function} and @code{x-group-function}
@end itemize
@node Configuration
@chapter Configuration
Vertico is available from @uref{http://elpa.gnu.org/packages/vertico.html, GNU ELPA}, such that it can be installed directly via
@code{package-install}. After installation, the global minor mode can be enabled with
@samp{M-x vertico-mode}. In order to configure Vertico and other packages in your
init.el, you may want to use @code{use-package}. Here is an example configuration:
@lisp
;; Enable vertico
(use-package vertico
:init
(vertico-mode))
;; Use the `orderless' completion style.
;; Enable `partial-completion' for files to allow path expansion.
;; You may prefer to use `initials' instead of `partial-completion'.
(use-package orderless
:init
(setq completion-styles '(orderless)
completion-category-defaults nil
completion-category-overrides '((file (styles . (partial-completion))))))
;; A few more useful configurations...
(use-package emacs
:init
;; Add prompt indicator to `completing-read-multiple'.
(defun crm-indicator (args)
(cons (concat "[CRM] " (car args)) (cdr args)))
(advice-add #'completing-read-multiple :filter-args #'crm-indicator)
;; Grow and shrink minibuffer
;;(setq resize-mini-windows t)
;; Do not allow the cursor in the minibuffer prompt
(setq minibuffer-prompt-properties
'(read-only t cursor-intangible t face minibuffer-prompt))
(add-hook 'minibuffer-setup-hook #'cursor-intangible-mode)
;; Enable recursive minibuffers
(setq enable-recursive-minibuffers t))
@end lisp
@node Keymap
@chapter Keymap
Vertico defines its own local keymap in the minibuffer which is derived from
@code{minibuffer-local-map}. The keymap mostly keeps the @code{fundamental-mode}
keybindings intact, but rebinds a few commands. Note in particular the binding
of @samp{TAB} to @code{vertico-insert} and the bindings of @code{vertico-exit/exit-input}.
@itemize
@item
@code{beginning-of-buffer}, @code{minibuffer-beginning-of-buffer} -> @code{vertico-beginning-of-buffer}
@item
@code{end-of-buffer} -> @code{vertico-end-of-buffer}
@item
@code{scroll-down-command} -> @code{vertico-scroll-down}
@item
@code{scroll-up-command} -> @code{vertico-scroll-up}
@item
@code{next-line}, @code{next-line-or-history-element} -> @code{vertico-next}
@item
@code{previous-line}, @code{previous-line-or-history-element} -> @code{vertico-previous}
@item
@code{exit-minibuffer} -> @code{vertico-exit}
@item
@code{kill-ring-save} -> @code{vertico-save}
@item
@samp{<C-return>} -> @code{vertico-exit-input}
@item
@samp{TAB} -> @code{vertico-insert}
@end itemize
Note that none of the bindings of the @code{minibuffer-local-completion-map} are
bound by default. If you prefer to have the default completion commands a key
press away you may want to add a few bindings. Then the default completion
commands will work as usual. For example you can use @samp{M-TAB} to cycle between
candidates if you have set @code{completion-cycle-threshold}.
@lisp
(define-key vertico-map "?" #'minibuffer-completion-help)
(define-key vertico-map "\M-\r" #'minibuffer-force-complete-and-exit)
(define-key vertico-map "\M-\t" #'minibuffer-complete)
@end lisp
If Vertico is active, you may want to disable the automatic @samp{*Completions*}
buffer by setting @code{completion-auto-help} to @code{nil} and make TAB-completion less
noisy by setting @code{completion-show-inline-help} to @code{nil}.
@lisp
(advice-add #'vertico--setup :after
(lambda (&rest _)
(setq-local completion-auto-help nil
completion-show-inline-help nil)))
@end lisp
@node Complementary packages
@chapter Complementary packages
Vertico works well together with a few complementary packages, which enrich the
completion UI@. These packages are fully supported:
@itemize
@item
@uref{https://github.com/minad/marginalia, Marginalia}: Rich annotations in the minibuffer
@item
@uref{https://github.com/minad/consult, Consult}: Many useful search and navigation commands
@item
@uref{https://github.com/oantolin/embark, Embark}: Minibuffer actions and context menu
@item
@uref{https://github.com/oantolin/orderless, Orderless}: Advanced completion style
@end itemize
@node Alternatives
@chapter Alternatives
There are many alternative completion UIs, each UI with its own advantages and
disadvantages. The @uref{https://github.com/raxod502/selectrum, Selectrum readme} provides an extensive comparison of many
available completion systems from the perspective of Selectrum.
Vertico aims to be fully compliant with all Emacs commands and achieves that
with a minimal code base, relying purely on @code{completing-read} while avoiding to
invent its own APIs. Inventing a custom API as Helm or Ivy is explicitly avoided
in order to increase flexibility and package reuse.
Since Vertico only provides the UI, you may want to combine it with some of the
complementary packages, to give a full-featured completion experience similar to
Ivy. Vertico is targeted at users interested in crafting their Emacs precisely
to their liking - completion plays an integral part in how the users interacts
with Emacs. There are at least two other interactive completion UIs, which
follow a similar philosophy:
@itemize
@item
@uref{https://github.com/raxod502/selectrum, Selectrum}: If you are looking for a less minimalistic and more full-featured
(but also more complex) package, you may be interested in Selectrum, which
provides a similar UI as Vertico. Additionally Selectrum supports Avy-style
quick keys, a horizontal display and a configurable buffer display.
@item
@uref{https://github.com/oantolin/icomplete-vertical, Icomplete-vertical}: This package enhances the Emacs builtin Icomplete with a
vertical display. In contrast to Vertico, the candidates are rotated such that
the current candidate always appears at the top. From my perspective,
candidate rotation feels a bit less intuitive than the UI provided by Vertico
or Selectrum.
@end itemize
@bye