Deprecate support for Selectrum

Selectrum doesn't fully support dynamic completion tables, which are widespread
in Emacs (find-file, completion-table-dynamic, ...) and has other technical
issues. Since there are multiple fully compliant completion UI alternatives
available, we phase out Selectrum support in Consult. Furthermore we consider
deprecating Selectrum in favor of Vertico. Vertico is simpler than Selectrum and
has been designed specifically to address the shortcomings of Selectrum. See
minad/vertico#237 and
https://github.com/minad/vertico/wiki/Migrating-from-Selectrum-to-Vertico.

In the future the plan is to only support UIs which are fully compliant in
Consult. For the package ecosystem it is better to stick to fully compliant UIs,
since this reduces the amount of UI-specific workarounds across the ecosystem.

If you have feedback regarding the deprecation, please let me know. For the time
being, the deprecation message can be disabled by adding the following to your
init.el:

(with-eval-after-load 'consult-selectrum
  (advice-remove 'consult--read 'consult-selectrum--deprecated))

CHANGELOG.org

@@ -15,6 +15,8 @@
   =consult-point-placement=, which is also used by the =consult-*grep= commands.
 - =consult-imenu=: Support imenu-after-jump-hook and non-default
   =imenu-default-goto-function=
+- Deprecate support for Selectrum in favor of Vertico. If you use Selectrum
+  consider switching to Vertico, Icomplete, Mct or default completion.
 
 * Version 0.19 (2022-09-09)
 

README.org

@@ -24,7 +24,7 @@ the command =consult-imenu= presents a flat list of the Imenu with [[#live-previ
 
 Consult is fully compatible with completion systems based on the standard Emacs
 =completing-read= API, notably the default completion system, [[https://github.com/minad/vertico][Vertico]], [[https://github.com/protesilaos/mct][Mct]],
-[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]] and [[https://github.com/radian-software/selectrum][Selectrum]].
+and [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]].
 
 This package keeps the completion system specifics to a minimum. The ability of
 the Consult commands to work well with arbitrary completion systems is one of
@@ -363,9 +363,7 @@ their descriptions.
 - =consult-completion-in-region=: In case you don't use [[https://github.com/minad/corfu][Corfu]] as your in-buffer
   completion UI, this function can be set as =completion-in-region-function=. Then
   your minibuffer completion UI (e.g., Vertico or Icomplete) will be used for
-  =completion-at-point=. Note that Selectrum provides its own variant of
-  =consult-completion-in-region=. If you use Mct, you may want to try
-  =mct-region-mode= instead.
+  =completion-at-point=. If you use Mct, you can give =mct-region-mode= a try.
   #+begin_src emacs-lisp
     ;; Use `consult-completion-in-region' if Vertico is enabled.
     ;; Otherwise use the default `completion--in-region' function.
@@ -1012,9 +1010,9 @@ you!
 
 - The builtin completion UI, which pops up the =*Completions*= buffer.
 - The builtin =icomplete-vertical-mode= in Emacs 28.
-- [[https://github.com/radian-software/selectrum][selectrum by Radon Rosborough]]: Alternative vertical UI, predecessor of Vertico.
 - [[https://git.sr.ht/~protesilaos/mct][mct by Protesilaos Stavrou]]: Minibuffer and Completions in Tandem, which builds
-  on the default completion UI (development [[https://protesilaos.com/codelog/2022-04-14-emacs-discontinue-mct/][discontinued]]).
+  on the default completion UI (development currently [[https://protesilaos.com/codelog/2022-04-14-emacs-discontinue-mct/][discontinued]]).
+- [[https://github.com/radian-software/selectrum][selectrum by Radon Rosborough]]: Superseded by Vertico (deprecated).
 
 You can integrated Consult with special programs or with other packages in the
 wider Emacs ecosystem. You may want to install some of theses packages depending
@@ -1072,7 +1070,7 @@ out the following steps:
    This includes Consult, Vertico or other completion UIs, Marginalia, Embark
    and Orderless.
 2. Either use the default completion UI or ensure that exactly one of
-   =vertico-mode=, =mct-mode=, =selectrum-mode=, or =icomplete-mode= is enabled.
+   =vertico-mode=, =mct-mode=, or =icomplete-mode= is enabled.
    The unsupported modes =ivy-mode=, =helm-mode= and =ido-ubiquitous-mode= must be disabled.
 3. Ensure that the =completion-styles= variable is properly configured. Try to set
    =completion-styles= to a list including =substring= or =orderless=.
@@ -1101,7 +1099,7 @@ Minimal setup with the default completion system for =emacs -Q=:
 Please provide the necessary important information with your bug report:
 
 - The minimal configuration snippet used to reproduce the issue.
-- Your completion UI (Default completion, Vertico, Mct, Selectrum or Icomplete).
+- Your completion UI (Default completion, Vertico, Mct or Icomplete).
 - A stack trace in case the bug triggers an exception.
 - Your Emacs version, since bugs may be fixed or introduced in newer versions.
 - Your operating system, since Emacs behavior varies between Linux, Mac and
@@ -1138,8 +1136,9 @@ small configuration or command snippets.
 :end:
 
 This package took inspiration from [[https://github.com/abo-abo/swiper#counsel][Counsel]] by Oleh Krehel. Some of the Consult
-commands originated in the Counsel package or the [[https://github.com/radian-software/selectrum/wiki/Useful-Commands][Selectrum wiki]]. The commands
-have been rewritten and greatly enhanced in comparison to the original versions.
+commands originated in the Counsel package or the wiki from the Selectrum
+package. The commands have been rewritten and greatly enhanced in comparison to
+the original versions.
 
 Code contributions:
 - [[https://github.com/oantolin/][Omar Antolín Camarena]]

consult-selectrum.el

@@ -86,11 +86,16 @@ SPLIT is the splitter function."
      selectrum-highlight-candidates-function
      (consult-selectrum--split-wrap selectrum-highlight-candidates-function split))))
 
+(defun consult-selectrum--deprecated (&rest _)
+  (warn "%s: Selectrum support has been deprecated in favor of Vertico" this-command)
+  (advice-remove #'consult--read #'consult-selectrum--deprecated))
+
 (add-hook 'consult--completion-candidate-hook #'consult-selectrum--candidate)
 (add-hook 'consult--completion-refresh-hook #'consult-selectrum--refresh)
 (advice-add #'consult--completion-filter :around #'consult-selectrum--filter-adv)
 (advice-add #'consult--split-setup :around #'consult-selectrum--split-setup-adv)
 (define-key consult-async-map [remap selectrum-insert-current-candidate] 'selectrum-next-page)
+(advice-add #'consult--read :before #'consult-selectrum--deprecated)
 
 (provide 'consult-selectrum)
 ;;; consult-selectrum.el ends here

consult.el

@@ -27,20 +27,21 @@
 ;;; Commentary:
 
 ;; Consult implements a set of `consult-<thing>' commands which use
-;; `completing-read' to select from a list of candidates. Consult provides an
-;; enhanced buffer switcher `consult-buffer' and search and navigation commands
-;; like `consult-imenu' and `consult-line'. Searching through multiple files is
-;; supported by the asynchronous `consult-grep' command. Many Consult commands
-;; allow previewing candidates - if a candidate is selected in the completion
-;; view, the buffer shows the candidate immediately.
-
-;; The Consult commands are compatible with completion systems based
-;; on the Emacs `completing-read' API, including the default completion
-;; system, Vertico, Mct, Icomplete and Selectrum.
+;; `completing-read' to select from a list of candidates. Consult
+;; provides an enhanced buffer switcher `consult-buffer' and search and
+;; navigation commands like `consult-imenu' and `consult-line'.
+;; Searching through multiple files is supported by the asynchronous
+;; `consult-grep' command. Many Consult commands allow previewing
+;; candidates - if a candidate is selected in the completion view, the
+;; buffer shows the candidate immediately.
+
+;; The Consult commands are compatible with completion systems based on
+;; the Emacs `completing-read' API, including the default completion
+;; system, Vertico, Mct and Icomplete.
 
 ;; Consult has been inspired by Counsel. Some of the Consult commands
-;; originated in the Counsel package or the Selectrum wiki. See the
-;; README for a full list of contributors.
+;; originated in the Counsel package or the wiki of the Selectrum
+;; package. See the README for a full list of contributors.
 
 ;;; Code: