branch: externals/vertico
commit 77c15c1a6b5f963fad18c380c3aeb4410dbd13b3
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
README: Expand section on empty input (See #208)
---
README.org | 30 ++++++++++++++++++++++--------
1 file changed, 22 insertions(+), 8 deletions(-)
diff --git a/README.org b/README.org
index 2dd0bae53f..eb2853cbbe 100644
--- a/README.org
+++ b/README.org
@@ -54,7 +54,7 @@ binding of =TAB= to ~vertico-insert~ and the bindings of
~vertico-exit/exit-inpu
- ~backward-paragraph~ -> ~vertico-previous-group~
- ~exit-minibuffer~ -> ~vertico-exit~
- ~kill-ring-save~ -> ~vertico-save~
-- =C-RET= -> ~vertico-exit-input~
+- =M-RET= -> ~vertico-exit-input~
- =TAB= -> ~vertico-insert~
* Configuration
@@ -556,15 +556,29 @@ disabled as follows.
(apply args))))
#+end_src
-** ~multi-occur~, ~auto-insert~, ~bbdb-create~
+** Submitting the empty string
-These commands read multiple arguments from the minibuffer, one at a
-time, until you submit an empty string. You should type =C-RET=
-(~vertico-exit-input~) to finish the loop.
+The commands ~multi-occur~, ~auto-insert~, ~bbdb-create~ read multiple
arguments from
+the minibuffer with ~completing-read~, one at a time, until you submit an empty
+string. You should type =M-RET= (~vertico-exit-input~) to finish the loop.
+Alternatively you can move the cursor to the prompt line and press =RET=.
Directly
+pressing =RET= (~vertico-exit~) does not work since the first candidate is
+preselected.
-Simply pressing =RET= (~vertico-exit~) does not work here because
-these commands require a match and Vertico gives no special treatment
-to the empty string.
+The underlying issue is that ~completing-read~ always allows you to exit with
the
+empty string, which is called the /null completion/, even if the
~REQUIRE-MATCH~
+argument is non-nil. Try the following two calls to ~completing-read~ with
=C-x C-e=:
+
+#+begin_src emacs-lisp
+ (completing-read "Select: " '("first" "second" "third") nil 'require-match)
+ (completing-read "Select: " '("first" "second" "third") nil 'require-match
nil nil "")
+#+end_src
+
+In both cases the empty string can be submitted. In the first case no explicit
+default value is specified and Vertico preselects the *first* candidate. In
order
+to exit with the empty string, press =M-RET=. In the second case the explicit
+default value "" is specified and Vertico preselects the prompt, such that
+existing with the empty string is possible by pressing =RET= only.
** Tramp hostname completion
