Improve cape-capf-sort

3 files changed, 21 insertions, 10 deletions

diff --git a/CHANGELOG.org b/CHANGELOG.org
index e15f360..830e3d8 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -5,6 +5,8 @@
 * Development
 
 - Mark ~cape-capf-purify~ and ~cape-wrap-purify~ as obsolete.
+- ~cape-capf-sort~: Make ~SORT~ function argument optional. If the ~SORT~ argument is
+  nil or not given, the completion UI sorting will take over.
 
 * Version 2.2 (2025-10-13)
 
diff --git a/README.org b/README.org
index c5a16c6..3652e30 100644
--- a/README.org
+++ b/README.org
@@ -176,12 +176,12 @@ with ~cape-capf-super~.
 /Throw multiple Capfs under the Cape and get a Super-Capf!/
 
 Cape supports merging multiple Capfs using the function ~cape-capf-super~. Due to
-some technical details, not all Capfs can be merged successfully. Merge Capfs
+technical details, not all Capfs can be merged successfully. Try to merge Capfs
 one by one and make sure that you get the desired outcome.
 
-Note that ~cape-capf-super~ is not needed if multiple Capfs should betried one
-after the other, for example you can use ~cape-file~ together with programming
-mode Capfs by adding ~cape-file~ to the ~completion-at-point-functions~ list. File
+Note that ~cape-capf-super~ is not needed if multiple Capfs should be tried one
+after another, for example you can use ~cape-file~ together with programming mode
+Capfs by adding ~cape-file~ to the ~completion-at-point-functions~ list. File
 completion will then be available in comments and string literals, but not in
 normal code. ~cape-capf-super~ is only necessary if you want to combine multiple
 Capfs, such that the candidates from multiple sources appear /together/ in the
@@ -194,15 +194,24 @@ and completion functions which do not define completion boundaries.
 static completion functions like ~cape-dabbrev~, ~cape-keyword~, ~cape-dict~, etc.,
 but not for multi-step completions like ~cape-file~.
 
+The results returned by the individual Capfs are listed after each other, where
+the the order of the completion candidates is preserved. In order to override
+this sorting behavior use ~cape-capf-sort~, such that the completion UI can apply
+its own sorting.
+
 #+begin_src emacs-lisp
 ;; Merge the dabbrev, dict and keyword capfs, display candidates together.
 (setq-local completion-at-point-functions
-            (list (cape-capf-super #'cape-dabbrev #'cape-dict #'cape-keyword)))
+            (list (cape-capf-super #'cape-dabbrev #'cape-dict)))
+
+;; Let the UI (e.g. Corfu) sort the candidates by overriding the sort function.
+(setq-local completion-at-point-functions
+            (list (cape-capf-sort (cape-capf-super #'cape-dabbrev #'cape-dict))))
 
-;; Alternative: Define named Capf instead of using the anonymous Capf directly
-(defun cape-dabbrev-dict-keyword ()
-  (cape-wrap-super #'cape-dabbrev #'cape-dict #'cape-keyword))
-(setq-local completion-at-point-functions (list #'cape-dabbrev-dict-keyword))
+;; Define named Capf instead of using the anonymous Capf directly.
+(defun cape-dabbrev-dict ()
+  (cape-wrap-super #'cape-dabbrev #'cape-dict))
+(setq-local completion-at-point-functions (list #'cape-dabbrev-dict))
 #+end_src
 
 See also the aforementioned ~company--multi-backend-adapter~ from Company, which
diff --git a/cape.el b/cape.el
index f369155..4e8e150 100644
--- a/cape.el
+++ b/cape.el
@@ -1110,7 +1110,7 @@ This function can be used as an advice around an existing Capf."
   (cape-wrap-properties capf :exclusive 'no))
 
 ;;;###autoload
-(defun cape-wrap-sort (capf sort)
+(defun cape-wrap-sort (capf &optional sort)
   "Call CAPF and add SORT function.
 This function can be used as an advice around an existing Capf."
   (cape-wrap-properties