[elpa] externals/consult 162d7d73ed 1/2: Deprecate support for Selectrum

[ELPA Syncer]

branch: externals/consult
commit 162d7d73edb63faa7dd72fcffb20af42886de6e0
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    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
    https://github.com/minad/vertico/issues/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        |  2 ++
 README.org           | 19 +++++++++----------
 consult-selectrum.el |  5 +++++
 consult.el           | 25 +++++++++++++------------
 4 files changed, 29 insertions(+), 22 deletions(-)

diff --git a/CHANGELOG.org b/CHANGELOG.org
index c358fb099f..cff4538894 100644
--- a/CHANGELOG.org
+++ b/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)
 
diff --git a/README.org b/README.org
index 10dfa60fc4..8fffaa6527 100644
--- a/README.org
+++ b/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]]
diff --git a/consult-selectrum.el b/consult-selectrum.el
index 706e0c6b78..2d4a922cb4 100644
--- a/consult-selectrum.el
+++ b/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
diff --git a/consult.el b/consult.el
index 9070cbc738..4b21e83646 100644
--- a/consult.el
+++ b/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: