Re: on helm substantial differences

[Juri Linkov]

> Before knowing what's the best approach, I think we should clearly
> decide what would be the "ideal" new API.  E.g. should it return "any
> string" and then it'd be up to the infrastructure code to store
> side-info about what is the corresponding candidate's actual text?

After trying different variants, it turned out that the most convenient
is to use annotation-function that can contain a placeholder for the
completion candidate.  Currently "%s" is used as a placeholder,
for example, "prefix %s suffix" but it can be any string.
Or maybe better to allow returning a list of two separate strings
for prefix and suffix from annotation-function?

Here is an example used for testing:

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 9d57a817b2..b98033753d 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -83,7 +80,6 @@
 
 ;; - add support for ** to pcm.
 ;; - Add vc-file-name-completion-table to read-file-name-internal.
-;; - A feature like completing-help.el.
 
 ;;; Code:
 
@@ -1754,13 +1753,22 @@ completion--insert-strings
             (if (not (consp str))
                 (put-text-property (point) (progn (insert str) (point))
                                    'mouse-face 'highlight)
-              (put-text-property (point) (progn (insert (car str)) (point))
-                                 'mouse-face 'highlight)
-              (let ((beg (point))
-                    (end (progn (insert (cadr str)) (point))))
-                (put-text-property beg end 'mouse-face nil)
-                (font-lock-prepend-text-property beg end 'face
-                                                 'completions-annotations)))
+              (let* ((split (split-string (cadr str) "%s"))
+                     (prefix (when (cadr split) (car split)))
+                     (suffix (or (cadr split) (car split))))
+                (when prefix
+                  (let ((beg (point))
+                        (end (progn (insert prefix) (point))))
+                    (put-text-property beg end 'mouse-face nil)
+                    (font-lock-prepend-text-property beg end 'face
+                                                     
'completions-annotations)))
+                (put-text-property (point) (progn (insert (car str)) (point))
+                                   'mouse-face 'highlight)
+                (let ((beg (point))
+                      (end (progn (insert suffix) (point))))
+                  (put-text-property beg end 'mouse-face nil)
+                  (font-lock-prepend-text-property beg end 'face
+                                                   'completions-annotations))))
            (cond
             ((eq completions-format 'vertical)
              ;; Vertical format
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 170f497541..00603272bf 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -127,16 +127,30 @@ help-enable-completion-autoload
   :version "26.3")
 
 (defun help--symbol-completion-table (string pred action)
-  (when help-enable-completion-autoload
-    (let ((prefixes (radix-tree-prefixes (help-definition-prefixes) string)))
-      (help--load-prefixes prefixes)))
-  (let ((prefix-completions
-         (and help-enable-completion-autoload
-              (mapcar #'intern (all-completions string definition-prefixes)))))
-    (complete-with-action action obarray string
-                          (if pred (lambda (sym)
-                                     (or (funcall pred sym)
-                                         (memq sym prefix-completions)))))))
+  (if (eq action 'metadata)
+      '(metadata
+       (annotation-function
+         . (lambda (c)
+             (let* ((s (intern c))
+                    (doc (condition-case nil (documentation s) (error nil)))
+                    (doc (and doc (substring doc 0 (string-match "\n" doc)))))
+               (format "%s %%s%s"
+                       (propertize (cond ((commandp s) "c")
+                                         ((fboundp s) "f")
+                                         ((boundp s) "v")
+                                         " ")
+                                   'face 'shadow)
+                       (if doc (propertize (format " -- %s" doc) 'face 
'shadow) ""))))))
+    (when help-enable-completion-autoload
+      (let ((prefixes (radix-tree-prefixes (help-definition-prefixes) string)))
+        (help--load-prefixes prefixes)))
+    (let ((prefix-completions
+           (and help-enable-completion-autoload
+                (mapcar #'intern (all-completions string 
definition-prefixes)))))
+      (complete-with-action action obarray string
+                            (if pred (lambda (sym)
+                                       (or (funcall pred sym)
+                                           (memq sym prefix-completions))))))))
 
 (defvar describe-function-orig-buffer nil
   "Buffer that was current when `describe-function' was invoked.