[elpa] externals/vertico 4c2a578: README: Document a few problematic completion commands

[Protesilaos Stavrou]

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

    README: Document a few problematic completion commands
    
    cc @clemera
---
 README.org   | 39 ++++++++++++++++++++++++++++++++++++++
 vertico.texi | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)

diff --git a/README.org b/README.org
index b221df6..f20f7ee 100644
--- a/README.org
+++ b/README.org
@@ -171,6 +171,45 @@ follow a similar philosophy:
   candidate rotation feels a bit less intuitive than the UI provided by Vertico
   or Selectrum.
 
+* Problematic completion commands
+
+** ~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.
+
+ #+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]].
+
+** ~Info-goto-node~
+
+ The command ~Info-goto-node~ uses the ~Info-read-node-name~ completion table,
+ which almost works as is with Vertico. However there is the issue that the
+ completion table sometimes throws unexpected errors (bug#47771).
+
+** ~tmm-menubar~
+
+ The text menu bar works well with Vertico but always shows a =*Completions*=
+ buffer, which is unwanted if you are using the Vertico UI. This completion
+ buffer can be disabled as follows.
+
+ #+begin_src emacs-lisp
+   (defun kill-completions () (kill-buffer "*Completions*"))
+   (advice-add #'tmm-add-prompt :after #'kill-completions)
+ #+end_src
+
 * Contributions
 
 Since this package is part of GNU ELPA, contributions require copyright
diff --git a/vertico.texi b/vertico.texi
index b132753..c02a6ab 100644
--- a/vertico.texi
+++ b/vertico.texi
@@ -32,7 +32,19 @@
 * TAB completion::
 * Complementary packages::
 * Alternatives::
+* Problematic completion commands::
 * Contributions::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Problematic completion commands
+
+* @code{org-set-tags-command}::
+* @code{Info-goto-node}::
+* @code{tmm-menubar}::
+
+@end detailmenu
 @end menu
 
 @node Introduction
@@ -236,6 +248,55 @@ candidate rotation feels a bit less intuitive than the UI 
provided by Vertico
 or Selectrum.
 @end itemize
 
+@node Problematic completion commands
+@chapter Problematic completion commands
+
+@menu
+* @code{org-set-tags-command}::
+* @code{Info-goto-node}::
+* @code{tmm-menubar}::
+@end menu
+
+@node @code{org-set-tags-command}
+@section @code{org-set-tags-command}
+
+@code{org-set-tags-command} implements a completion table which relies on the 
@code{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.
+
+@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 lisp
+
+In order to fix the issues properly, @code{org-set-tags-command} should be
+implemented using @code{completing-read-multiple} as discussed on the 
@uref{https://lists.gnu.org/archive/html/emacs-orgmode/2020-07/msg00222.html, 
mailing list}.
+
+@node @code{Info-goto-node}
+@section @code{Info-goto-node}
+
+The command @code{Info-goto-node} uses the @code{Info-read-node-name} 
completion table,
+which almost works as is with Vertico. However there is the issue that the
+completion table sometimes throws unexpected errors (bug#47771).
+
+@node @code{tmm-menubar}
+@section @code{tmm-menubar}
+
+The text menu bar works well with Vertico but always shows a 
@samp{*Completions*}
+buffer, which is unwanted if you are using the Vertico UI@. This completion
+buffer can be disabled as follows.
+
+@lisp
+(defun kill-completions () (kill-buffer "*Completions*"))
+(advice-add #'tmm-add-prompt :after #'kill-completions)
+@end lisp
+
 @node Contributions
 @chapter Contributions