[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/vertico 2a80b9e25c 3/3: README: Reindent
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/vertico 2a80b9e25c 3/3: README: Reindent |
|
Date: |
Mon, 14 Feb 2022 11:57:57 -0500 (EST) |
branch: externals/vertico
commit 2a80b9e25c82d38bd5a8951226d3c5e7807789b2
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>
README: Reindent
---
README.org | 751 ++++++++++++++++++++++++++++++-------------------------------
1 file changed, 374 insertions(+), 377 deletions(-)
diff --git a/README.org b/README.org
index a7b70b547f..00ebf257b7 100644
--- a/README.org
+++ b/README.org
@@ -13,258 +13,257 @@
* Introduction
- Vertico provides a performant and minimalistic vertical completion UI based
on
- the default completion system. The main focus of Vertico is to provide a UI
- which behaves /correctly/ under all circumstances. By reusing the built-in
- facilities system, Vertico achieves /full compatibility/ with built-in Emacs
- completion commands and completion tables. Vertico only provides the
- completion UI but aims to be highly flexible, extensible and modular.
- Additional enhancements are available as [[#extensions][extensions]] or
[[#complementary-packages][complementary packages]].
- The code base is small and maintainable. The main ~vertico.el~ package is
only
- about 600 lines of code without white space and comments.
+Vertico provides a performant and minimalistic vertical completion UI based on
+the default completion system. The main focus of Vertico is to provide a UI
+which behaves /correctly/ under all circumstances. By reusing the built-in
+facilities system, Vertico achieves /full compatibility/ with built-in Emacs
+completion commands and completion tables. Vertico only provides the completion
+UI but aims to be highly flexible, extensible and modular. Additional
+enhancements are available as [[#extensions][extensions]] or
[[#complementary-packages][complementary packages]]. The code
+base is small and maintainable. The main ~vertico.el~ package is only about 600
+lines of code without white space and comments.
* Features
- - Vertical display with arrow key navigation. See the
[[#extensions][extensions]] for additional display modes.
- - Prompt shows the current candidate index and the total number of
candidates.
- - The current candidate is inserted with =TAB= and selected with =RET=.
- - Non-existing candidates can be submitted with =C-return= or by moving the
point to the prompt.
- - Configurable sorting by history position, length and alphabetically.
- - Long candidates with newlines are formatted to take up less space.
- - Deferred completion style highlighting for performance.
- - Annotations are displayed next to the candidates (~annotation-~ and
~affixation-function~).
- - Support for candidate grouping and group cycling commands
(~group-function~).
+- Vertical display with arrow key navigation. See the
[[#extensions][extensions]] for additional display modes.
+- Prompt shows the current candidate index and the total number of candidates.
+- The current candidate is inserted with =TAB= and selected with =RET=.
+- Non-existing candidates can be submitted with =C-return= or by moving the
point to the prompt.
+- Configurable sorting by history position, length and alphabetically.
+- Long candidates with newlines are formatted to take up less space.
+- Deferred completion style highlighting for performance.
+- Annotations are displayed next to the candidates (~annotation-~ and
~affixation-function~).
+- Support for candidate grouping and group cycling commands (~group-function~).
- [[https://github.com/minad/vertico/blob/screenshots/vertico-mx.png?raw=true]]
+[[https://github.com/minad/vertico/blob/screenshots/vertico-mx.png?raw=true]]
* Key bindings
- Vertico defines its own local keymap in the minibuffer which is derived from
- ~minibuffer-local-map~. The keymap keeps most of the ~fundamental-mode~
- keybindings intact and remaps and binds only a handful of commands. Note in
- particular the binding of =TAB= to ~vertico-insert~ and the bindings of
- ~vertico-exit/exit-input~.
-
- - ~beginning-of-buffer~, ~minibuffer-beginning-of-buffer~ -> ~vertico-first~
- - ~end-of-buffer~ -> ~vertico-last~
- - ~scroll-down-command~ -> ~vertico-scroll-down~
- - ~scroll-up-command~ -> ~vertico-scroll-up~
- - ~next-line~, ~next-line-or-history-element~ -> ~vertico-next~
- - ~previous-line~, ~previous-line-or-history-element~ -> ~vertico-previous~
- - ~forward-paragraph~ -> ~vertico-next-group~
- - ~backward-paragraph~ -> ~vertico-previous-group~
- - ~exit-minibuffer~ -> ~vertico-exit~
- - ~kill-ring-save~ -> ~vertico-save~
- - =C-return= -> ~vertico-exit-input~
- - =TAB= -> ~vertico-insert~
+Vertico defines its own local keymap in the minibuffer which is derived from
+~minibuffer-local-map~. The keymap keeps most of the ~fundamental-mode~
keybindings
+intact and remaps and binds only a handful of commands. Note in particular the
+binding of =TAB= to ~vertico-insert~ and the bindings of
~vertico-exit/exit-input~.
+
+- ~beginning-of-buffer~, ~minibuffer-beginning-of-buffer~ -> ~vertico-first~
+- ~end-of-buffer~ -> ~vertico-last~
+- ~scroll-down-command~ -> ~vertico-scroll-down~
+- ~scroll-up-command~ -> ~vertico-scroll-up~
+- ~next-line~, ~next-line-or-history-element~ -> ~vertico-next~
+- ~previous-line~, ~previous-line-or-history-element~ -> ~vertico-previous~
+- ~forward-paragraph~ -> ~vertico-next-group~
+- ~backward-paragraph~ -> ~vertico-previous-group~
+- ~exit-minibuffer~ -> ~vertico-exit~
+- ~kill-ring-save~ -> ~vertico-save~
+- =C-return= -> ~vertico-exit-input~
+- =TAB= -> ~vertico-insert~
* Configuration
- Vertico is available from [[http://elpa.gnu.org/packages/vertico.html][GNU
ELPA]]. You can install it directly via
- ~package-install~. After installation, you can activate the global minor mode
- with =M-x vertico-mode=. In order to configure Vertico and other packages in
- your init.el, you may want to take advantage of ~use-package~. I recommend to
- give Orderless completion a try, which is different from the prefix TAB
- completion used by the basic default completion system or in shells. Here is
- an example configuration:
-
- #+begin_src emacs-lisp
- ;; Enable vertico
- (use-package vertico
- :init
- (vertico-mode)
-
- ;; Different scroll margin
- ;; (setq vertico-scroll-margin 0)
-
- ;; Show more candidates
- ;; (setq vertico-count 20)
-
- ;; Grow and shrink the Vertico minibuffer
- ;; (setq vertico-resize t)
-
- ;; Optionally enable cycling for `vertico-next' and `vertico-previous'.
- ;; (setq vertico-cycle t)
- )
-
- ;; Optionally use the `orderless' completion style. See
- ;; `+orderless-dispatch' in the Consult wiki for an advanced Orderless
style
- ;; dispatcher. Additionally enable `partial-completion' for file path
- ;; expansion. `partial-completion' is important for wildcard support.
- ;; Multiple files can be opened at once with `find-file' if you enter a
- ;; wildcard. You may also give the `initials' completion style a try.
- (use-package orderless
- :init
- ;; Configure a custom style dispatcher (see the Consult wiki)
- ;; (setq orderless-style-dispatchers '(+orderless-dispatch)
- ;; orderless-component-separator
#'orderless-escapable-split-on-space)
- (setq completion-styles '(orderless)
- completion-category-defaults nil
- completion-category-overrides '((file (styles
partial-completion)))))
-
- ;; Persist history over Emacs restarts. Vertico sorts by history position.
- (use-package savehist
- :init
- (savehist-mode))
-
- ;; A few more useful configurations...
- (use-package emacs
- :init
- ;; Add prompt indicator to `completing-read-multiple'.
- ;; Alternatively try `consult-completing-read-multiple'.
- (defun crm-indicator (args)
- (cons (concat "[CRM] " (car args)) (cdr args)))
- (advice-add #'completing-read-multiple :filter-args #'crm-indicator)
-
- ;; 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)
-
- ;; Emacs 28: Hide commands in M-x which do not work in the current mode.
- ;; Vertico commands are hidden in normal buffers.
- ;; (setq read-extended-command-predicate
- ;; #'command-completion-default-include-p)
-
- ;; Enable recursive minibuffers
- (setq enable-recursive-minibuffers t))
- #+end_src
-
- See also the [[https://github.com/minad/vertico/wiki][Vertico Wiki]] for
additional configuration tips. For more general
- documentation read the chapter about completion in the
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html][Emacs
manual]]. If you
- want to create your own completion commands, you can find documentation about
- completion in the
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html][Elisp
manual]].
+Vertico is available from [[http://elpa.gnu.org/packages/vertico.html][GNU
ELPA]]. You can install it directly via
+~package-install~. After installation, you can activate the global minor mode
with
+=M-x vertico-mode=. In order to configure Vertico and other packages in your
+init.el, you may want to take advantage of ~use-package~. I recommend to give
+Orderless completion a try, which is different from the prefix TAB completion
+used by the basic default completion system or in shells. Here is an example
+configuration:
+
+#+begin_src emacs-lisp
+ ;; Enable vertico
+ (use-package vertico
+ :init
+ (vertico-mode)
+
+ ;; Different scroll margin
+ ;; (setq vertico-scroll-margin 0)
+
+ ;; Show more candidates
+ ;; (setq vertico-count 20)
+
+ ;; Grow and shrink the Vertico minibuffer
+ ;; (setq vertico-resize t)
+
+ ;; Optionally enable cycling for `vertico-next' and `vertico-previous'.
+ ;; (setq vertico-cycle t)
+ )
+
+ ;; Optionally use the `orderless' completion style. See
+ ;; `+orderless-dispatch' in the Consult wiki for an advanced Orderless style
+ ;; dispatcher. Additionally enable `partial-completion' for file path
+ ;; expansion. `partial-completion' is important for wildcard support.
+ ;; Multiple files can be opened at once with `find-file' if you enter a
+ ;; wildcard. You may also give the `initials' completion style a try.
+ (use-package orderless
+ :init
+ ;; Configure a custom style dispatcher (see the Consult wiki)
+ ;; (setq orderless-style-dispatchers '(+orderless-dispatch)
+ ;; orderless-component-separator
#'orderless-escapable-split-on-space)
+ (setq completion-styles '(orderless)
+ completion-category-defaults nil
+ completion-category-overrides '((file (styles partial-completion)))))
+
+ ;; Persist history over Emacs restarts. Vertico sorts by history position.
+ (use-package savehist
+ :init
+ (savehist-mode))
+
+ ;; A few more useful configurations...
+ (use-package emacs
+ :init
+ ;; Add prompt indicator to `completing-read-multiple'.
+ ;; Alternatively try `consult-completing-read-multiple'.
+ (defun crm-indicator (args)
+ (cons (concat "[CRM] " (car args)) (cdr args)))
+ (advice-add #'completing-read-multiple :filter-args #'crm-indicator)
+
+ ;; 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)
+
+ ;; Emacs 28: Hide commands in M-x which do not work in the current mode.
+ ;; Vertico commands are hidden in normal buffers.
+ ;; (setq read-extended-command-predicate
+ ;; #'command-completion-default-include-p)
+
+ ;; Enable recursive minibuffers
+ (setq enable-recursive-minibuffers t))
+#+end_src
+
+See also the [[https://github.com/minad/vertico/wiki][Vertico Wiki]] for
additional configuration tips. For more general
+documentation read the chapter about completion in the
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html][Emacs
manual]]. If you want
+to create your own completion commands, you can find documentation about
+completion in the
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html][Elisp
manual]].
** Completion styles and TAB completion
- The bindings of the ~minibuffer-local-completion-map~ are not available in
- Vertico by default. This means that TAB works differently from what you may
- expect from the default Emacs completion system.
-
- If you prefer to have the default completion commands a key press away you
can
- add new bindings or even replace the Vertico bindings. Then the default
- completion commands behave as usual. For example you can use =M-TAB= to cycle
- between candidates if you have set ~completion-cycle-threshold~.
-
- #+begin_src emacs-lisp
- (define-key vertico-map "?" #'minibuffer-completion-help)
- (define-key vertico-map (kbd "M-RET") #'minibuffer-force-complete-and-exit)
- (define-key vertico-map (kbd "M-TAB") #'minibuffer-complete)
- #+end_src
-
- The ~orderless~ completion style does not support completion of a common
prefix
- substring, as you may be familiar with from shells or the basic default
- completion system. The reason is that the Orderless input string is usually
- not a prefix. In order to support completing prefixes you may want to combine
- ~orderless~ with ~substring~ in your =completion-styles= configuration.
-
- #+begin_src emacs-lisp
- (setq completion-styles '(substring orderless))
- #+end_src
-
- Alternatively you can experiment with the built-in completion-styles, e.g.,
- adding =partial-completion= or =flex=. The =partial-completion= style is
important
- to add if you want to open multiple files at once with ~find-file~ using
- wildcards. In order to open multiple files at once, you have to move to the
- prompt and then press =RET=.
-
- #+begin_src emacs-lisp
- (setq completion-styles '(basic substring partial-completion flex))
- #+end_src
-
- Because Vertico is fully compatible with Emacs default completion
- system, further customization of completion behavior can be achieved
- by setting the designated Emacs variables. For example, one may wish
- to disable case-sensitivity for file and buffer matching when built-in
- completion styles are used instead of ~orderless~:
-
- #+begin_src emacs-lisp
- (setq read-file-name-completion-ignore-case t
- read-buffer-completion-ignore-case t
- completion-ignore-case t)
- #+end_src
+The bindings of the ~minibuffer-local-completion-map~ are not available in
Vertico
+by default. This means that TAB works differently from what you may expect from
+the default Emacs completion system.
+
+If you prefer to have the default completion commands a key press away you can
+add new bindings or even replace the Vertico bindings. Then the default
+completion commands behave as usual. For example you can use =M-TAB= to cycle
+between candidates if you have set ~completion-cycle-threshold~.
+
+#+begin_src emacs-lisp
+ (define-key vertico-map "?" #'minibuffer-completion-help)
+ (define-key vertico-map (kbd "M-RET") #'minibuffer-force-complete-and-exit)
+ (define-key vertico-map (kbd "M-TAB") #'minibuffer-complete)
+#+end_src
+
+The ~orderless~ completion style does not support completion of a common prefix
+substring, as you may be familiar with from shells or the basic default
+completion system. The reason is that the Orderless input string is usually not
+a prefix. In order to support completing prefixes you may want to combine
+~orderless~ with ~substring~ in your =completion-styles= configuration.
+
+#+begin_src emacs-lisp
+ (setq completion-styles '(substring orderless))
+#+end_src
+
+Alternatively you can experiment with the built-in completion-styles, e.g.,
+adding =partial-completion= or =flex=. The =partial-completion= style is
important to
+add if you want to open multiple files at once with ~find-file~ using
wildcards.
+In order to open multiple files at once, you have to move to the prompt and
then
+press =RET=.
+
+#+begin_src emacs-lisp
+ (setq completion-styles '(basic substring partial-completion flex))
+#+end_src
+
+Because Vertico is fully compatible with Emacs default completion system,
+further customization of completion behavior can be achieved by setting the
+designated Emacs variables. For example, one may wish to disable
+case-sensitivity for file and buffer matching when built-in completion styles
+are used instead of ~orderless~:
+
+#+begin_src emacs-lisp
+ (setq read-file-name-completion-ignore-case t
+ read-buffer-completion-ignore-case t
+ completion-ignore-case t)
+#+end_src
** Completion-at-point and completion-in-region
- The =completion-at-point= command is usually bound to =M-TAB= or =TAB=. In
case you
- want to use Vertico for completion-at-point/completion-in-region, you can use
- the function ~consult-completion-in-region~ provided by the Consult package.
+The =completion-at-point= command is usually bound to =M-TAB= or =TAB=. In
case you
+want to use Vertico for completion-at-point/completion-in-region, you can use
+the function ~consult-completion-in-region~ provided by the Consult package.
- #+begin_src emacs-lisp
- ;; Use `consult-completion-in-region' if Vertico is enabled.
- ;; Otherwise use the default `completion--in-region' function.
- (setq completion-in-region-function
- (lambda (&rest args)
- (apply (if vertico-mode
- #'consult-completion-in-region
- #'completion--in-region)
- args)))
- #+end_src
+#+begin_src emacs-lisp
+ ;; Use `consult-completion-in-region' if Vertico is enabled.
+ ;; Otherwise use the default `completion--in-region' function.
+ (setq completion-in-region-function
+ (lambda (&rest args)
+ (apply (if vertico-mode
+ #'consult-completion-in-region
+ #'completion--in-region)
+ args)))
+#+end_src
- The =completion-in-region-function= setting also affects TAB completion in
the
- minibuffer when =M-:= (~eval-expression~) is used.
+The =completion-in-region-function= setting also affects TAB completion in the
+minibuffer when =M-:= (~eval-expression~) is used.
- You may also want to look into my [[https://github.com/minad/corfu][Corfu]]
package, which provides a minimal
- completion system for =completion-in-region= in a child frame popup. Corfu is
- also a narrowly focused package and developed in the same spirit as Vertico.
+You may also want to look into my [[https://github.com/minad/corfu][Corfu]]
package, which provides a minimal
+completion system for =completion-in-region= in a child frame popup. Corfu is
also
+a narrowly focused package and developed in the same spirit as Vertico.
** Completing-read-multiple (CRM)
- Consult offers an enhanced =completing-read-multiple= implementation which
you
- can use with Vertico.
+Consult offers an enhanced =completing-read-multiple= implementation which you
can
+use with Vertico.
- #+begin_src emacs-lisp
- (advice-add #'completing-read-multiple
- :override #'consult-completing-read-multiple)
- #+end_src
+#+begin_src emacs-lisp
+ (advice-add #'completing-read-multiple
+ :override #'consult-completing-read-multiple)
+#+end_src
* Extensions
:properties:
:custom_id: extensions
:end:
- We maintain small extension packages to Vertico in this repository in the
- subdirectory
[[https://github.com/minad/vertico/tree/main/extensions][extensions/]]. The
extensions are installed together with Vertico
- if you pull the package from ELPA. The extensions are inactive by default and
- can be enabled manually if desired. Furthermore it is possible to install all
- of the files separately, both ~vertico.el~ and the ~vertico-*.el~ extensions.
- Currently the following extensions come with the Vertico ELPA package:
-
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-buffer.el][vertico-buffer]]:
=vertico-buffer-mode= to display Vertico in a separate buffer.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-directory.el][vertico-directory]]:
Commands for Ido-like directory navigation.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-flat.el][vertico-flat]]:
=vertico-flat-mode= to enable a flat, horizontal display.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-grid.el][vertico-grid]]:
=vertico-grid-mode= to enable a grid display.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-indexed.el][vertico-indexed]]:
=vertico-indexed-mode= to select indexed candidates with prefix arguments.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-mouse.el][vertico-mouse]]:
=vertico-mouse-mode= to support for scrolling and candidate selection.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-multiform.el][vertico-multiform]]:
Configure Vertico modes per command or completion category.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-quick.el][vertico-quick]]:
Commands to select using Avy-style quick keys.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-repeat.el][vertico-repeat]]:
The command =vertico-repeat= repeats the last completion session.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-reverse.el][vertico-reverse]]:
=vertico-reverse-mode= to reverse the display.
- -
[[https://github.com/minad/vertico/blob/main/extensions/vertico-unobtrusive.el][vertico-unobtrusive]]:
=vertico-unobtrusive-mode= displays only the topmost candidate.
-
- With these extensions it is possible to adapt Vertico such that it matches
- your preference or behaves similar to other familiar UIs. For example, the
- combination =vertico-flat= plus =vertico-directory= resembles Ido in look and
- feel. For an interface similar to Helm, the extension =vertico-buffer= allows
- you to configure freely where the completion buffer opens, instead of growing
- the minibuffer. Furthermore =vertico-buffer= will adjust the number of
displayed
- candidates according to the buffer height.
-
- Configuration example for =vertico-directory=:
-
- #+begin_src emacs-lisp
- ;; Configure directory extension.
- (use-package vertico-directory
- :after vertico
- :ensure nil
- ;; More convenient directory navigation commands
- :bind (:map vertico-map
- ("RET" . vertico-directory-enter)
- ("DEL" . vertico-directory-delete-char)
- ("M-DEL" . vertico-directory-delete-word))
- ;; Tidy shadowed file names
- :hook (rfn-eshadow-update-overlay . vertico-directory-tidy))
- #+end_src
+We maintain small extension packages to Vertico in this repository in the
+subdirectory
[[https://github.com/minad/vertico/tree/main/extensions][extensions/]]. The
extensions are installed together with Vertico if
+you pull the package from ELPA. The extensions are inactive by default and can
+be enabled manually if desired. Furthermore it is possible to install all of
the
+files separately, both ~vertico.el~ and the ~vertico-*.el~ extensions.
Currently the
+following extensions come with the Vertico ELPA package:
+
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-buffer.el][vertico-buffer]]:
=vertico-buffer-mode= to display Vertico in a separate buffer.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-directory.el][vertico-directory]]:
Commands for Ido-like directory navigation.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-flat.el][vertico-flat]]:
=vertico-flat-mode= to enable a flat, horizontal display.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-grid.el][vertico-grid]]:
=vertico-grid-mode= to enable a grid display.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-indexed.el][vertico-indexed]]:
=vertico-indexed-mode= to select indexed candidates with prefix arguments.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-mouse.el][vertico-mouse]]:
=vertico-mouse-mode= to support for scrolling and candidate selection.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-multiform.el][vertico-multiform]]:
Configure Vertico modes per command or completion category.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-quick.el][vertico-quick]]:
Commands to select using Avy-style quick keys.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-repeat.el][vertico-repeat]]:
The command =vertico-repeat= repeats the last completion session.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-reverse.el][vertico-reverse]]:
=vertico-reverse-mode= to reverse the display.
+-
[[https://github.com/minad/vertico/blob/main/extensions/vertico-unobtrusive.el][vertico-unobtrusive]]:
=vertico-unobtrusive-mode= displays only the topmost candidate.
+
+With these extensions it is possible to adapt Vertico such that it matches your
+preference or behaves similar to other familiar UIs. For example, the
+combination =vertico-flat= plus =vertico-directory= resembles Ido in look and
feel.
+For an interface similar to Helm, the extension =vertico-buffer= allows you to
+configure freely where the completion buffer opens, instead of growing the
+minibuffer. Furthermore =vertico-buffer= will adjust the number of displayed
+candidates according to the buffer height.
+
+Configuration example for =vertico-directory=:
+
+#+begin_src emacs-lisp
+ ;; Configure directory extension.
+ (use-package vertico-directory
+ :after vertico
+ :ensure nil
+ ;; More convenient directory navigation commands
+ :bind (:map vertico-map
+ ("RET" . vertico-directory-enter)
+ ("DEL" . vertico-directory-delete-char)
+ ("M-DEL" . vertico-directory-delete-word))
+ ;; Tidy shadowed file names
+ :hook (rfn-eshadow-update-overlay . vertico-directory-tidy))
+#+end_src
** Configure Vertico per command or completion category
@@ -372,39 +371,38 @@ candidates from disappearing when they scroll off-screen
to the left.
:custom_id: complementary-packages
:end:
- Vertico integrates well with complementary packages, which enrich the
- completion UI. These packages are fully supported:
-
- - [[https://github.com/minad/marginalia][Marginalia]]: Rich annotations in
the minibuffer
- - [[https://github.com/minad/consult][Consult]]: Useful search and
navigation commands
- - [[https://github.com/oantolin/embark][Embark]]: Minibuffer actions and
context menu
- - [[https://github.com/oantolin/orderless][Orderless]]: Advanced completion
style
-
- In order to get accustomed with the package ecosystem, I recommed the
- following quick start approach:
-
- 1. Start with plain Emacs (~emacs -Q~).
- 2. Install and enable Vertico to get incremental minibuffer completion.
- 3. Install Orderless and/or configure the built-in completion styles
- for more flexible minibuffer filtering.
- 4. Install Marginalia if you like rich minibuffer annotations.
- 5. Install Embark and add two keybindings for ~embark-dwim~ and ~embark-act~.
- I am using the mnemonic keybindings =M-.= and =C-.= since these commands
allow
- you to act on the object at point or in the minibuffer.
- 6. Install Consult if you want additional featureful completion commands,
- e.g, the buffer switcher ~consult-buffer~ with preview or the line-based
- search ~consult-line~.
- 7. Install Embark-Consult and Wgrep for export from =consult-line= to
=occur-mode=
- buffers and from =consult-grep= to editable =grep-mode= buffers.
- 8. Fine tune Vertico with [[#extensions][extensions]].
-
- The ecosystem is modular. You don't have to use all of these components. Use
- only the ones you like and the ones which fit well into your setup. The
- steps 1. to 4. introduce no new commands over plain Emacs. Step 5. introduces
- the new commands ~embark-act~ and ~embark-dwim~. In step 6. you get the
Consult
- commands, some offer new functionality not present in Emacs already (e.g.,
- ~consult-line~) and some are substitutes (e.g., ~consult-buffer~ for
- ~switch-to-buffer~).
+Vertico integrates well with complementary packages, which enrich the
completion
+UI. These packages are fully supported:
+
+- [[https://github.com/minad/marginalia][Marginalia]]: Rich annotations in the
minibuffer
+- [[https://github.com/minad/consult][Consult]]: Useful search and navigation
commands
+- [[https://github.com/oantolin/embark][Embark]]: Minibuffer actions and
context menu
+- [[https://github.com/oantolin/orderless][Orderless]]: Advanced completion
style
+
+In order to get accustomed with the package ecosystem, I recommed the following
+quick start approach:
+
+1. Start with plain Emacs (~emacs -Q~).
+2. Install and enable Vertico to get incremental minibuffer completion.
+3. Install Orderless and/or configure the built-in completion styles
+ for more flexible minibuffer filtering.
+4. Install Marginalia if you like rich minibuffer annotations.
+5. Install Embark and add two keybindings for ~embark-dwim~ and ~embark-act~.
+ I am using the mnemonic keybindings =M-.= and =C-.= since these commands
allow
+ you to act on the object at point or in the minibuffer.
+6. Install Consult if you want additional featureful completion commands,
+ e.g., the buffer switcher ~consult-buffer~ with preview or the line-based
+ search ~consult-line~.
+7. Install Embark-Consult and Wgrep for export from =consult-line= to
=occur-mode=
+ buffers and from =consult-grep= to editable =grep-mode= buffers.
+8. Fine tune Vertico with [[#extensions][extensions]].
+
+The ecosystem is modular. You don't have to use all of these components. Use
+only the ones you like and the ones which fit well into your setup. The steps
1.
+to 4. introduce no new commands over plain Emacs. Step 5. introduces the new
+commands ~embark-act~ and ~embark-dwim~. In step 6. you get the Consult
commands,
+some offer new functionality not present in Emacs already (e.g.,
~consult-line~)
+and some are substitutes (e.g., ~consult-buffer~ for ~switch-to-buffer~).
* Child frames and Popups
@@ -427,53 +425,53 @@ yourself.
* Alternatives
- There are many alternative completion UIs, each UI with its own advantages
and
- disadvantages.
-
- Vertico aims to be 100% compliant with all Emacs commands and achieves that
- with a minimal code base, relying purely on ~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. Due to its small
- code base and reuse of the Emacs built-in facilities, bugs and compatibility
- issues are less likely to occur in comparison to completion UIs or full
- completion systems, which reimplement a lot of functionality.
-
- 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 Helm or Ivy. Overall the packages in the spirit of Vertico have a
- different style than Helm or Ivy. The idea is to have smaller independent
- components, which one can add and understand step by step. Each component
- focuses on its niche and tries to be as non-intrusive as possible. Vertico
- targets users interested in crafting their Emacs precisely to their liking -
- completion plays an integral part in how the users interacts with Emacs.
-
- There are other interactive completion UIs, which follow a similar
philosophy:
-
- - [[https://github.com/raxod502/selectrum][Selectrum]]: Selectrum has a
similar UI as Vertico, since it directly inspired
- Vertico. The Selectrum code base is more complex. Unfortunately Selectrum
is
- not fully compatible with every Emacs completion command
([[https://github.com/raxod502/selectrum/issues/481][Issue #481]]), since
- it uses its own filtering infrastructure, which deviates from the standard
- Emacs completion facilities. Vertico additionally has the ability to cycle
- over candidates, offers commands for grouping support and comes with a rich
- set of [[#extensions][extensions]].
- - [[https://github.com/oantolin/icomplete-vertical][Icomplete-vertical]]:
This package enhances the Emacs builtin Icomplete with a
- vertical display. In contrast to Vertico, Icomplete rotates the candidates
- such that the current candidate always appears at the top. From my
- perspective, candidate rotation feels a bit less intuitive than the UI of
- Vertico or Selectrum. Note that Emacs 28 offers a built-in
- ~icomplete-vertical-mode~.
- - [[https://gitlab.com/protesilaos/mct][Mct]]: Minibuffer and Completions in
Tandem. Mct reuses the default ~*Completions*~
- buffer and enhances it with automatic updates and additional keybindings,
to
- select a candidate and move between minibuffer and completions buffer. Mct
- is great if you prefer an unobtrusive UI since it can be configured to open
- only when requested. Furthermore since Mct uses a fully functional buffer
- you can reuse all your familar buffer commands inside the completions
- buffer. The main distinction to Vertico's approach is that ~*Completions*~
- buffer displays all matching candidates. On the one hand this is good since
- it allows you to interact with all the candidates and jump around with
- Isearch or Avy. On the other hand it necessarily causes a slowdown in
- comparison to Vertico, which only displays a subset of candidates. Mct
- supports completion in region via its ~mct-region-mode~.
+There are many alternative completion UIs, each UI with its own advantages and
+disadvantages.
+
+Vertico aims to be 100% compliant with all Emacs commands and achieves that
with
+a minimal code base, relying purely on ~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. Due to its small code base and
+reuse of the Emacs built-in facilities, bugs and compatibility issues are less
+likely to occur in comparison to completion UIs or full completion systems,
+which reimplement a lot of functionality.
+
+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
+Helm or Ivy. Overall the packages in the spirit of Vertico have a different
+style than Helm or Ivy. The idea is to have smaller independent components,
+which one can add and understand step by step. Each component focuses on its
+niche and tries to be as non-intrusive as possible. Vertico targets users
+interested in crafting their Emacs precisely to their liking - completion plays
+an integral part in how the users interacts with Emacs.
+
+There are other interactive completion UIs, which follow a similar philosophy:
+
+- [[https://github.com/raxod502/selectrum][Selectrum]]: Selectrum has a
similar UI as Vertico, since it directly inspired
+ Vertico. The Selectrum code base is more complex. Unfortunately Selectrum is
+ not fully compatible with every Emacs completion command
([[https://github.com/raxod502/selectrum/issues/481][Issue #481]]), since
+ it uses its own filtering infrastructure, which deviates from the standard
+ Emacs completion facilities. Vertico additionally has the ability to cycle
+ over candidates, offers commands for grouping support and comes with a rich
+ set of [[#extensions][extensions]].
+- [[https://github.com/oantolin/icomplete-vertical][Icomplete-vertical]]: This
package enhances the Emacs builtin Icomplete with a
+ vertical display. In contrast to Vertico, Icomplete rotates the candidates
+ such that the current candidate always appears at the top. From my
+ perspective, candidate rotation feels a bit less intuitive than the UI of
+ Vertico or Selectrum. Note that Emacs 28 offers a built-in
+ ~icomplete-vertical-mode~.
+- [[https://gitlab.com/protesilaos/mct][Mct]]: Minibuffer and Completions in
Tandem. Mct reuses the default ~*Completions*~
+ buffer and enhances it with automatic updates and additional keybindings, to
+ select a candidate and move between minibuffer and completions buffer. Mct is
+ great if you prefer an unobtrusive UI since it can be configured to open only
+ when requested. Furthermore since Mct uses a fully functional buffer you can
+ reuse all your familar buffer commands inside the completions buffer. The
main
+ distinction to Vertico's approach is that ~*Completions*~ buffer displays all
+ matching candidates. On the one hand this is good since it allows you to
+ interact with all the candidates and jump around with Isearch or Avy. On the
+ other hand it necessarily causes a slowdown in comparison to Vertico, which
+ only displays a subset of candidates. Mct supports completion in region via
+ its ~mct-region-mode~.
* Resources
@@ -499,88 +497,87 @@ If you want to learn more about Vertico, check out the
following resources:
** ~org-refile~
- ~org-refile~ uses ~org-olpath-completing-read~ to complete the outline path
- in steps, when ~org-refile-use-outline-path~ is non-nil.
-
- Unfortunately the implementation of this Org completion table assumes that
- the ~basic~ completion style is used. The table is incompatible with
completion
- styles like ~substring~, ~flex~ or ~orderless~. In order to fix the issue
at the
- root, the completion table should make use of completion boundaries similar
- to the built-in file completion table. In your user configuration you can
- prioritize ~basic~ before ~orderless~.
-
- #+begin_src emacs-lisp
- ;; Alternative 1: Use the basic completion style
- (setq org-refile-use-outline-path 'file
- org-outline-path-complete-in-steps t)
- (advice-add #'org-olpath-completing-read :around
- (lambda (&rest args)
- (minibuffer-with-setup-hook
- (lambda () (setq-local completion-styles '(basic)))
- (apply args))))
- #+end_src
-
- Alternatively you may want to disable the outline path completion in steps.
- The completion on the full path can be quicker since the input string
matches
- directly against substrings of the full path, which is useful with
Orderless.
- However the list of possible completions becomes much more cluttered.
-
- #+begin_src emacs-lisp
- ;; Alternative 2: Complete full paths
- (setq org-refile-use-outline-path 'file
- org-outline-path-complete-in-steps nil)
- #+end_src
+~org-refile~ uses ~org-olpath-completing-read~ to complete the outline path in
+steps, when ~org-refile-use-outline-path~ is non-nil.
+
+Unfortunately the implementation of this Org completion table assumes that the
+~basic~ completion style is used. The table is incompatible with completion
styles
+like ~substring~, ~flex~ or ~orderless~. In order to fix the issue at the
root, the
+completion table should make use of completion boundaries similar to the
+built-in file completion table. In your user configuration you can prioritize
+~basic~ before ~orderless~.
+
+#+begin_src emacs-lisp
+ ;; Alternative 1: Use the basic completion style
+ (setq org-refile-use-outline-path 'file
+ org-outline-path-complete-in-steps t)
+ (advice-add #'org-olpath-completing-read :around
+ (lambda (&rest args)
+ (minibuffer-with-setup-hook
+ (lambda () (setq-local completion-styles '(basic)))
+ (apply args))))
+#+end_src
+
+Alternatively you may want to disable the outline path completion in steps. The
+completion on the full path can be quicker since the input string matches
+directly against substrings of the full path, which is useful with Orderless.
+However the list of possible completions becomes much more cluttered.
+
+#+begin_src emacs-lisp
+ ;; Alternative 2: Complete full paths
+ (setq org-refile-use-outline-path 'file
+ org-outline-path-complete-in-steps nil)
+#+end_src
** ~tmm-menubar~
- The text menu bar works well with Vertico but always shows a =*Completions*=
- buffer, which is unwanted if you use the Vertico UI. This completion buffer
- can be disabled with an advice. If you disabled the standard GUI menu bar
and
- prefer the Vertico interface you may also overwrite the default F10
- keybinding.
+The text menu bar works well with Vertico but always shows a =*Completions*=
+buffer, which is unwanted if you use the Vertico UI. This completion buffer can
+be disabled with an advice. If you disabled the standard GUI menu bar and
prefer
+the Vertico interface you may also overwrite the default F10 keybinding.
- #+begin_src emacs-lisp
- (global-set-key [f10] #'tmm-menubar)
- (advice-add #'tmm-add-prompt :after #'minibuffer-hide-completions)
- #+end_src
+#+begin_src emacs-lisp
+ (global-set-key [f10] #'tmm-menubar)
+ (advice-add #'tmm-add-prompt :after #'minibuffer-hide-completions)
+#+end_src
** ~ffap-menu~
- The command ~ffap-menu~ shows the =*Completions*= buffer by default like
- ~tmm-menubar~, which is unnecessary with Vertico. This completion buffer
can be
- disabled as follows.
+The command ~ffap-menu~ shows the =*Completions*= buffer by default like
+~tmm-menubar~, which is unnecessary with Vertico. This completion buffer can be
+disabled as follows.
- #+begin_src emacs-lisp
- (advice-add #'ffap-menu-ask :around (lambda (&rest args)
- (cl-letf (((symbol-function
#'minibuffer-completion-help)
- #'ignore))
- (apply args))))
- #+end_src
+#+begin_src emacs-lisp
+ (advice-add #'ffap-menu-ask :around (lambda (&rest args)
+ (cl-letf (((symbol-function
#'minibuffer-completion-help)
+ #'ignore))
+ (apply args))))
+#+end_src
** Tramp hostname completion
- In combination with Orderless, hostnames are not made available for
- completion after entering =/ssh:=. In order to avoid this problem, the
=basic=
- completion style should be specified for the file completion category.
-
- #+begin_src emacs-lisp
- (setq completion-styles '(orderless)
- completion-category-overrides '((file (styles basic
partial-completion))))
- #+end_src
-
- For users who are familiar with the =completion-style= machinery: You may
also
- define a custom completion style which sets in only for remote files!
-
- #+begin_src emacs-lisp
- (defun basic-remote-try-completion (string table pred point)
- (and (vertico--remote-p string)
- (completion-basic-try-completion string table pred point)))
- (defun basic-remote-all-completions (string table pred point)
- (and (vertico--remote-p string)
- (completion-basic-all-completions string table pred point)))
- (add-to-list
- 'completion-styles-alist
- '(basic-remote basic-remote-try-completion basic-remote-all-completions
nil))
- (setq completion-styles '(orderless)
- completion-category-overrides '((file (styles basic-remote
partial-completion))))
- #+end_src
+In combination with Orderless, hostnames are not made available for completion
+after entering =/ssh:=. In order to avoid this problem, the =basic= completion
style
+should be specified for the file completion category.
+
+#+begin_src emacs-lisp
+ (setq completion-styles '(orderless)
+ completion-category-overrides '((file (styles basic
partial-completion))))
+#+end_src
+
+For users who are familiar with the =completion-style= machinery: You may also
+define a custom completion style which sets in only for remote files!
+
+#+begin_src emacs-lisp
+ (defun basic-remote-try-completion (string table pred point)
+ (and (vertico--remote-p string)
+ (completion-basic-try-completion string table pred point)))
+ (defun basic-remote-all-completions (string table pred point)
+ (and (vertico--remote-p string)
+ (completion-basic-all-completions string table pred point)))
+ (add-to-list
+ 'completion-styles-alist
+ '(basic-remote basic-remote-try-completion basic-remote-all-completions
nil))
+ (setq completion-styles '(orderless)
+ completion-category-overrides '((file (styles basic-remote
partial-completion))))
+#+end_src