[elpa] externals/vertico 86ed39e 2/7: Indent readme

[ELPA Syncer]

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

    Indent readme
---
 README.org | 394 ++++++++++++++++++++++++++++++-------------------------------
 1 file changed, 197 insertions(+), 197 deletions(-)

diff --git a/README.org b/README.org
index a421d03..bf831ef 100644
--- a/README.org
+++ b/README.org
@@ -12,211 +12,211 @@
 
 * Introduction
 
-Vertico provides a performant and minimalistic vertical completion UI, which is
-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. Additional enhancements can be installed separately via complementary
-packages. The code base is small and maintainable (~vertico.el~ is only about 
600
-lines of code without whitespace and comments).
+  Vertico provides a performant and minimalistic vertical completion UI, which 
is
+  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. Additional enhancements can be installed separately via complementary
+  packages. The code base is small and maintainable (~vertico.el~ is only 
about 600
+  lines of code without whitespace and comments).
 
 * Features
 
-- Vertical display with arrow key navigation
-- 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 entered by moving the point to the prompt line
-- Sorting by history position, string length and alphabetically
-- Long candidates with newlines are formatted to take up less space
-- Deferred completion style highlighting for performance
-- Support for annotations (~annotation-function~ and ~affixation-function~)
-- Support for grouping and group cycling commands (~group-function~)
+  - Vertical display with arrow key navigation
+  - 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 entered by moving the point to the prompt 
line
+  - Sorting by history position, string length and alphabetically
+  - Long candidates with newlines are formatted to take up less space
+  - Deferred completion style highlighting for performance
+  - Support for annotations (~annotation-function~ and ~affixation-function~)
+  - Support for grouping and group cycling commands (~group-function~)
 
-[[https://github.com/minad/vertico/blob/main/screenshot.svg?raw=true]]
+  [[https://github.com/minad/vertico/blob/main/screenshot.svg?raw=true]]
 
 * Configuration
 
-Vertico is available from [[http://elpa.gnu.org/packages/vertico.html][GNU 
ELPA]], such that it can be installed directly via
-~package-install~. After installation, the global minor mode can be enabled 
with
-=M-x vertico-mode=. In order to configure Vertico and other packages in your
-init.el, you may want to use ~use-package~. I recommend to give orderless
-completion a try, which is different from the familiar prefix TAB completion.
-Here is an example configuration:
-
-#+begin_src emacs-lisp
-  ;; Enable vertico
-  (use-package vertico
-    :init
-    (vertico-mode)
-
-    ;; Grow and shrink the Vertico minibuffer
-    ;; (setq vertico-resize t)
-
-    ;; Optionally enable cycling for `vertico-next' and `vertico-previous'.
-    ;; (setq vertico-cycle t)
-  )
-
-  ;; 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)))))
-
-  ;; 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)
-
-    ;; Enable recursive minibuffers
-    (setq enable-recursive-minibuffers t))
-#+end_src
+  Vertico is available from [[http://elpa.gnu.org/packages/vertico.html][GNU 
ELPA]], such that it can be installed directly via
+  ~package-install~. After installation, the global minor mode can be enabled 
with
+  =M-x vertico-mode=. In order to configure Vertico and other packages in your
+  init.el, you may want to use ~use-package~. I recommend to give orderless
+  completion a try, which is different from the familiar prefix TAB completion.
+  Here is an example configuration:
+
+  #+begin_src emacs-lisp
+    ;; Enable vertico
+    (use-package vertico
+      :init
+      (vertico-mode)
+
+      ;; Grow and shrink the Vertico minibuffer
+      ;; (setq vertico-resize t)
+
+      ;; Optionally enable cycling for `vertico-next' and `vertico-previous'.
+      ;; (setq vertico-cycle t)
+      )
+
+    ;; 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)))))
+
+    ;; 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)
+
+      ;; Enable recursive minibuffers
+      (setq enable-recursive-minibuffers t))
+  #+end_src
 
 * Key bindings
 
-Vertico defines its own local keymap in the minibuffer which is derived from
-~minibuffer-local-map~. The keymap mostly keeps the ~fundamental-mode~
-keybindings intact and remaps and binds only a few 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 mostly keeps the ~fundamental-mode~
+  keybindings intact and remaps and binds only a few 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~
 
 * 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 will work 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 TAB prefix completion. In
-order to enable that you may want to combine ~orderless~ with ~substring~, or
-not use ~orderless~ at all.
-
-#+begin_src emacs-lisp
-  (setq completion-styles '(substring orderless))
-  (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)
-#+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 will work 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 TAB prefix completion. In
+  order to enable that you may want to combine ~orderless~ with ~substring~, or
+  not use ~orderless~ at all.
+
+  #+begin_src emacs-lisp
+    (setq completion-styles '(substring orderless))
+    (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)
+  #+end_src
 
 * Complementary packages
 
-Vertico works well together with a few complementary packages, which enrich the
-completion UI. These packages are fully supported:
+  Vertico works well together with a few 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]]: Many 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
+  - [[https://github.com/minad/marginalia][Marginalia]]: Rich annotations in 
the minibuffer
+  - [[https://github.com/minad/consult][Consult]]: Many 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 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.
+  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.
-  (add-hook 'vertico-mode-hook (lambda ()
-                                 (setq completion-in-region-function
-                                       (if vertico-mode
-                                           #'consult-completion-in-region
-                                         #'completion--in-region))))
-#+end_src
+  #+begin_src emacs-lisp
+    ;; Use `consult-completion-in-region' if Vertico is enabled.
+    (add-hook 'vertico-mode-hook (lambda ()
+                                   (setq completion-in-region-function
+                                         (if vertico-mode
+                                             #'consult-completion-in-region
+                                           #'completion--in-region))))
+  #+end_src
 
-Furthermore Consult offers an enhanced =completing-read-multiple= 
implementation,
-which works well with Vertico.
+  Furthermore Consult offers an enhanced =completing-read-multiple= 
implementation,
+  which works well 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
 
-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 using overlays. Corfu is 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 using overlays. Corfu is 
developed in
+  the same spirit as Vertico.
 
 * 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 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
-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:
-
-- [[https://github.com/raxod502/selectrum][Selectrum]]: Selectrum has a 
similar UI as Vertico. Vertico additionally has
-  the ability to cycle over candidates and offers more commands for grouping
-  support. On the other hand, Selectrum supports Avy-style quick keys and a
-  horizontal display. Furthermore Selectrum is significantly more complex and
-  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.
-- [[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 of Vertico or
-  Selectrum. Note that Emacs 28 offers a built-in ~icomplete-vertical-mode~.
-
-See also the [[https://github.com/raxod502/selectrum][Selectrum readme]], 
which gives an extensive comparison of many
-available completion systems from the perspective of Selectrum.
+  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 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
+  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:
+
+  - [[https://github.com/raxod502/selectrum][Selectrum]]: Selectrum has a 
similar UI as Vertico. Vertico additionally has
+    the ability to cycle over candidates and offers more commands for grouping
+    support. On the other hand, Selectrum supports Avy-style quick keys and a
+    horizontal display. Furthermore Selectrum is significantly more complex and
+    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.
+  - [[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 of Vertico or
+    Selectrum. Note that Emacs 28 offers a built-in ~icomplete-vertical-mode~.
+
+  See also the [[https://github.com/raxod502/selectrum][Selectrum readme]], 
which gives an extensive comparison of many
+  available completion systems from the perspective of Selectrum.
 
 * Problematic completion commands
 
@@ -227,23 +227,23 @@ available completion systems from the perspective of 
Selectrum.
 
 ** ~org-set-tags-command~
 
- ~org-set-tags-command~ implements a completion table which relies on the 
~basic~
- completion style and TAB completion. This table does not work well with 
Vertico
- and Icomplete. The issue can be mitigated by deactivating most of the Vertico 
UI
- and relying purely on TAB completion. The UI is still enhanced by Vertico, 
since
- Vertico shows the available tags.
+   ~org-set-tags-command~ implements a completion table which relies on the 
~basic~
+   completion style and TAB completion. This table does not work well with 
Vertico
+   and Icomplete. The issue can be mitigated by deactivating most of the 
Vertico UI
+   and relying purely on TAB completion. The UI is still enhanced by Vertico, 
since
+   Vertico shows the available tags.
 
- #+begin_src emacs-lisp
-   (defun disable-selection ()
-     (when (eq minibuffer-completion-table #'org-tags-completion-function)
-       (setq-local vertico-map minibuffer-local-completion-map
-                   completion-cycle-threshold nil
-                   completion-styles '(basic))))
-   (advice-add #'vertico--setup :before #'disable-selection)
- #+end_src
+   #+begin_src emacs-lisp
+     (defun disable-selection ()
+       (when (eq minibuffer-completion-table #'org-tags-completion-function)
+         (setq-local vertico-map minibuffer-local-completion-map
+                     completion-cycle-threshold nil
+                     completion-styles '(basic))))
+     (advice-add #'vertico--setup :before #'disable-selection)
+   #+end_src
 
- In order to fix the issues properly, ~org-set-tags-command~ should be
- implemented using ~completing-read-multiple~ as discussed on the 
[[https://lists.gnu.org/archive/html/emacs-orgmode/2020-07/msg00222.html][mailing
 list]].
+   In order to fix the issues properly, ~org-set-tags-command~ should be
+   implemented using ~completing-read-multiple~ as discussed on the 
[[https://lists.gnu.org/archive/html/emacs-orgmode/2020-07/msg00222.html][mailing
 list]].
 
 ** ~org-refile~
 
@@ -305,5 +305,5 @@ available completion systems from the perspective of 
Selectrum.
 
 * Contributions
 
-Since this package is part of [[http://elpa.gnu.org/packages/vertico.html][GNU 
ELPA]] contributions require a copyright
-assignment to the FSF.
+  Since this package is part of 
[[http://elpa.gnu.org/packages/vertico.html][GNU ELPA]] contributions require a 
copyright
+  assignment to the FSF.