[elpa] externals/vertico 4e984005dd 2/4: Document vertico-multiform

[ELPA Syncer]

branch: externals/vertico
commit 4e984005dd854dd00bc9e3767fb9d1d4cefe4fc5
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    Document vertico-multiform
    
    The `vertico-multiform` extension solves an issue I wanted to have fixed for
    quite some time: It makes it possible to configure the Vertico display or
    arbitrary modes per command or completion category, e.g., turning on the
    `vertico-grid-mode` only for the command `find-file`. Until now it has only 
been
    possible to turn on `vertico-grid-mode` or `vertico-buffer-mode` globally, 
which
    wastes a lot of flexibility. The `vertico-multiform` package is still
    experimental - turning modes on and off when entering and leaving recursive
    minibuffers may introduce edge cases.
    
    There is an interesting use case described by @abcdw described in
    https://github.com/minad/consult/issues/486. Andrew uses @protesilaos' Mct 
and
    configures it separately for each command. For commands like 
`consult-imenu`,
    `consult-outline`, etc. he prefers a separate large buffer since the 
command is
    meant to navigate within the current buffer. For buffer switching commands 
like
    `find-file`, `switch-to-buffer` the selected window can be reused instead, 
keeping
    the window layout intact.
---
 README.org | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 55 insertions(+), 6 deletions(-)

diff --git a/README.org b/README.org
index 211ea011b0..fbff202ed1 100644
--- a/README.org
+++ b/README.org
@@ -237,7 +237,7 @@
   - 
[[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-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.
@@ -246,8 +246,9 @@
   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 more freely where the completion buffer opens, instead of
-  growing the minibuffer.
+  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=:
 
@@ -265,6 +266,55 @@
       :hook (rfn-eshadow-update-overlay . vertico-directory-tidy))
   #+end_src
 
+** Configure Vertico per-command or completion category
+
+Vertico offers the =vertico-multiform-mode= which allows you to configure 
Vertico
+per command or per completion category. The =vertico-buffer-mode= enables a
+Helm-like buffer display, which takes more space but also displays more
+candidates. This verbose display mode is useful for commands like 
~consult-imenu~
+or ~consult-outline~ since the buffer display allows you to get a better 
overview
+over the entire current buffer.
+
+#+begin_src emacs-lisp
+  ;; Enable vertico-multiform
+  (vertico-multiform-mode)
+
+  ;; Configure the display per command.
+  ;; Use a buffer with indices for imenu
+  ;; and a flat (Ido-like) menu for M-x.
+  (setq vertico-multiform-command-modes
+        '((consult-imenu buffer indexed)
+          (execute-extended-command flat)))
+
+  ;; Configure the display per completion category.
+  ;; Use the grid display for files and a buffer
+  ;; for the consult-grep commands.
+  (setq vertico-multiform-category-modes
+        '((file grid)
+          (consult-grep buffer)))
+#+end_src
+
+You can use your own functions or even lambdas to configure the per command (or
+per category) completion behavior. The function must have the same calling
+convention as a mode, i.e., it takes a single argument, which is either 1 to
+turn on the mode and -1 to turn off the mode.
+
+#+begin_src emacs-lisp
+  ;; Configure `consult-outline' as a scaled down TOC in a separate buffer
+  (setq vertico-multiform-command-modes
+        '((consult-outline buffer (lambda (_) (text-scale-decrease 1)))))
+#+end_src
+
+Furthermore you can tune buffer-local settings per command (or category).
+
+#+begin_src emacs-lisp
+  ;; Change the default sorting function
+  (setq vertico-multiform-command-settings
+        '((describe-symbol (vertico-sort-function . vertico-sort-alpha))))
+  (setq vertico-multiform-category-settings
+        '((symbol (vertico-sort-function . vertico-sort-alpha))))
+#+end_src
+
 * Complementary packages
   :properties:
   :custom_id: complementary-packages
@@ -398,9 +448,8 @@ packages a try and judge for yourself.
 
    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 particularily useful
-   with Orderless. However the list of possible completions becomes much more
-   cluttered.
+   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