[ELPA] New package: marginalia

[ELPA] New package: marginalia

[Daniel Mendler]

We want to submit the package "marginalia" to GNU ELPA. The package
enhances existing commands with completion categories and
`annotation/affixation-functions` for rich annotations.

Marginalia works with the default *Completions* UI, Vertico (GNU ELPA),
Selectrum (MELPA) and Icomplete-vertical (MELPA). Ivy (GNU ELPA) support
is in the works; there is an open PR
(https://github.com/abo-abo/swiper/pull/2875).

The Marginalia source and a README can be found at
https://github.com/minad/marginalia.

Thank you!

Daniel Mendler
(co-maintainer with Omar Antolín Camarena)

Re: [ELPA] New package: marginalia

[Stefan Monnier]

> We want to submit the package "marginalia" to GNU ELPA. The package
> enhances existing commands with completion categories and
> `annotation/affixation-functions` for rich annotations.

I'd welcome this in GNU ELPA, *but* I can't find Omar in the
`copyright.list`.  So I think we'd need him to sign the copyright
paperwork first, unless I missed something.

BTW, I hope we can merge some of that code directly into Emacs itself.


        Stefan

Re: [ELPA] New package: marginalia

[Daniel Mendler]

On 5/28/21 3:47 PM, Stefan Monnier wrote:
>> We want to submit the package "marginalia" to GNU ELPA. The package
>> enhances existing commands with completion categories and
>> `annotation/affixation-functions` for rich annotations.
> 
> I'd welcome this in GNU ELPA, *but* I can't find Omar in the
> `copyright.list`.  So I think we'd need him to sign the copyright
> paperwork first, unless I missed something.

Thank you! Omar signed the papers just recently, so it could be that the
list is not yet updated.

> BTW, I hope we can merge some of that code directly into Emacs itself.

 Of course, but note the long discussions regarding how the
`affixation/annotation-function` should be revamped ;)

Daniel

Re: [ELPA] New package: marginalia

[Eli Zaretskii]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Date: Fri, 28 May 2021 15:59:00 +0200
> Cc: Omar Antolín Camarena <omar@matem.unam.mx>,
>  João Távora <joaotavora@gmail.com>,
>  "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> > I'd welcome this in GNU ELPA, *but* I can't find Omar in the
> > `copyright.list`.  So I think we'd need him to sign the copyright
> > paperwork first, unless I missed something.
> 
> Thank you! Omar signed the papers just recently, so it could be that the
> list is not yet updated.

The copyright clerk indeed wrote that the process is complete, but the
list was not updated yet.

Re: [ELPA] New package: marginalia

[Juri Linkov]

> BTW, I hope we can merge some of that code directly into Emacs itself.

For example, marginalia--symbol-class adds new symbol characters to
the replacement of `help--symbol-completion-table-affixation',
but it would be better to add new characters directly to
`help--symbol-completion-table-affixation'...

Re: [ELPA] New package: marginalia

[Daniel Mendler]

On 5/28/21 8:40 PM, Juri Linkov wrote:
>> BTW, I hope we can merge some of that code directly into Emacs itself.
> 
> For example, marginalia--symbol-class adds new symbol characters to
> the replacement of `help--symbol-completion-table-affixation',
> but it would be better to add new characters directly to
> `help--symbol-completion-table-affixation'...

Yes, I would be glad if you merge back the `marginalia--symbol-class` to
the Emacs help system! The `marginalia--symbol-class` has been inspired
by your `help--symbol-completion-table-affixation`, but I wanted to go a
little step further in Marginalia. Maybe it makes sense to add
`help--symbol-class` such that the function can be reused potentially at
other places?

Daniel

Re: [ELPA] New package: marginalia

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 730 bytes --]

>>> BTW, I hope we can merge some of that code directly into Emacs itself.
>> 
>> For example, marginalia--symbol-class adds new symbol characters to
>> the replacement of `help--symbol-completion-table-affixation',
>> but it would be better to add new characters directly to
>> `help--symbol-completion-table-affixation'...
>
> Yes, I would be glad if you merge back the `marginalia--symbol-class` to
> the Emacs help system! The `marginalia--symbol-class` has been inspired
> by your `help--symbol-completion-table-affixation`, but I wanted to go a
> little step further in Marginalia. Maybe it makes sense to add
> `help--symbol-class` such that the function can be reused potentially at
> other places?

Maybe something like


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help--symbol-class.patch --]
[-- Type: text/x-diff, Size: 2597 bytes --]

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 5a805a2302..133763add1 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -126,29 +126,35 @@ help-enable-completion-autoload
   :group 'help
   :version "26.3")
 
+(defun help--symbol-class (s)
+  "Return symbol class characters for symbol S."
+  (when (stringp s)
+    (setq s (intern-soft s)))
+  (cond ((commandp s)
+         "c")                           ; command
+        ((eq (car-safe (symbol-function s)) 'macro)
+         "m")                           ; macro
+        ((fboundp s)
+         "f")                           ; function
+        ((custom-variable-p s)
+         "u")                           ; user option
+        ((boundp s)
+         "v")                           ; variable
+        ((facep s)
+         "a")                           ; fAce
+        ((and (fboundp 'cl-find-class)
+              (cl-find-class s))
+         "t")                           ; CL type
+        (" ")                           ; something else
+        ))
+
 (defun help--symbol-completion-table-affixation (completions)
   (mapcar (lambda (c)
             (let* ((s (intern c))
                    (doc (condition-case nil (documentation s) (error nil)))
                    (doc (and doc (substring doc 0 (string-match "\n" doc)))))
               (list c (propertize
-                       (concat (cond ((commandp s)
-                                      "c") ; command
-                                     ((eq (car-safe (symbol-function s)) 'macro)
-                                      "m") ; macro
-                                     ((fboundp s)
-                                      "f") ; function
-                                     ((custom-variable-p s)
-                                      "u") ; user option
-                                     ((boundp s)
-                                      "v") ; variable
-                                     ((facep s)
-                                      "a") ; fAce
-                                     ((and (fboundp 'cl-find-class)
-                                           (cl-find-class s))
-                                      "t")  ; CL type
-                                     (" ")) ; something else
-                               " ")         ; prefix separator
+                       (concat (help--symbol-class s) " ") ; prefix separator
                        'face 'completions-annotations)
                     (if doc (propertize (format " -- %s" doc)
                                         'face 'completions-annotations)

[-- Attachment #3: Type: text/plain, Size: 115 bytes --]


Then you could use it, and prepend/append more characters
such as: o for obsolete, ! for advised, * for modified.

Re: [ELPA] New package: marginalia

[Daniel Mendler]

On 6/1/21 10:54 PM, Juri Linkov wrote:
>>>> BTW, I hope we can merge some of that code directly into Emacs itself.
>>>
>>> For example, marginalia--symbol-class adds new symbol characters to
>>> the replacement of `help--symbol-completion-table-affixation',
>>> but it would be better to add new characters directly to
>>> `help--symbol-completion-table-affixation'...
>>
>> Yes, I would be glad if you merge back the `marginalia--symbol-class` to
>> the Emacs help system! The `marginalia--symbol-class` has been inspired
>> by your `help--symbol-completion-table-affixation`, but I wanted to go a
>> little step further in Marginalia. Maybe it makes sense to add
>> `help--symbol-class` such that the function can be reused potentially at
>> other places?
> 
> Maybe something like...
> Then you could use it, and prepend/append more characters
> such as: o for obsolete, ! for advised, * for modified.

I am not sure if we would benefit much from this in Marginalia, since we
would still have to check the type of the symbol.

What about adding the extended `symbol-class` function from Marginalia
directly to help-fns.el? Note that the Marginalia function returns
multiple characters "fv" if a symbol denotes both a function and a variable.

Do you want to keep the `symbol-class` to be a single character under
all circumstances?

Daniel

~~~
(defun marginalia--symbol-class (s)
  "Return symbol class characters for symbol S.

Function:
f function
c command
m macro
! advised
o obsolete

Variable:
u custom
v variable
l local
* modified
o obsolete

Other:
a face
t cl-type"
  (format
   "%-6s"
   (concat
    (when (fboundp s)
      (concat
       (and (get s 'byte-obsolete-info) "o")
       (cond
        ((commandp s) "c")
        ((eq (car-safe (symbol-function s)) 'macro) "m")
        (t "f"))
       (and (marginalia--advised s) "!")))
    (when (boundp s)
      (concat
       (and (get s 'byte-obsolete-variable) "o")
       (and (local-variable-if-set-p s) "l")
       (if (custom-variable-p s) "u" "v")
       (and (ignore-errors (not (equal (symbol-value s) (default-value
s)))) "*")))
    (and (facep s) "a")
    (and (fboundp 'cl-find-class) (cl-find-class s) "t"))))
~~~

Re: [ELPA] New package: marginalia

[Juri Linkov]

> What about adding the extended `symbol-class` function from Marginalia
> directly to help-fns.el? Note that the Marginalia function returns
> multiple characters "fv" if a symbol denotes both a function and a variable.
>
> Do you want to keep the `symbol-class` to be a single character under
> all circumstances?

Not strictly under all circumstances, but I'd prefer not to turn it
into symbolic notation of file permissions such as drwxr-xr-x :-)
Maybe it's possible to keep 1 character, and highlight it with
different faces, e.g. dimmed out for obsolete, red for advised, etc.

Re: [ELPA] New package: marginalia

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 1384 bytes --]

> What about adding the extended `symbol-class` function from Marginalia
> directly to help-fns.el? Note that the Marginalia function returns
> multiple characters "fv" if a symbol denotes both a function and a variable.
>
> Do you want to keep the `symbol-class` to be a single character under
> all circumstances?

I have tried to use marginalia--symbol-class for help--symbol-class,
and noticed a few problems:

1. It's hard to visually scan the column with types
   when the primary char (f, c, v, u) is not the first in the row.
   In the following patch I moved the primary char to the beginning.

2. Also it would help to see the letter of the primary char
   if secondary chars are not letters.  So I replaced "o" (obsolete)
   with a strikethrough symbol "-".

3. Are Unicode characters allowed?  Then could we add to the primary char
   e.g. COMBINING LONG STROKE OVERLAY (U+0336) to designate obsolete.

4. The remaining secondary letter is "l" for local, but I can't find
   a non-letter character to replace it.

5. Isn't using formatting such as "%-6s" not suitable in the backend?
   At least, I moved it out of help--symbol-class.  Ideally,
   the frontend should adjust column sizes to fit them to the longest value.

6. The format "%-6s " with 7 placeholders that is too wide for most symbols
   when a tiny fraction of symbols has 4 chars max, so reduced it to 4:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help--symbol-class.patch --]
[-- Type: text/x-diff, Size: 2313 bytes --]

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 133763add1..804ab43063 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -130,23 +130,25 @@ help--symbol-class
   "Return symbol class characters for symbol S."
   (when (stringp s)
     (setq s (intern-soft s)))
-  (cond ((commandp s)
-         "c")                           ; command
-        ((eq (car-safe (symbol-function s)) 'macro)
-         "m")                           ; macro
-        ((fboundp s)
-         "f")                           ; function
-        ((custom-variable-p s)
-         "u")                           ; user option
-        ((boundp s)
-         "v")                           ; variable
-        ((facep s)
-         "a")                           ; fAce
-        ((and (fboundp 'cl-find-class)
-              (cl-find-class s))
-         "t")                           ; CL type
-        (" ")                           ; something else
-        ))
+  (concat
+   (when (fboundp s)
+     (concat
+      (cond
+       ((commandp s) "c")
+       ((eq (car-safe (symbol-function s)) 'macro) "m")
+       (t "f"))
+      (and (let ((flist (indirect-function s)))
+             (advice--p (if (eq 'macro (car-safe flist)) (cdr flist) flist)))
+           "!")
+      (and (get s 'byte-obsolete-info) "-")))
+   (when (boundp s)
+     (concat
+      (if (custom-variable-p s) "u" "v")
+      (and (local-variable-if-set-p s) "l")
+      (and (ignore-errors (not (equal (symbol-value s) (default-value s)))) "*")
+      (and (get s 'byte-obsolete-variable) "-")))
+   (and (facep s) "a")
+   (and (fboundp 'cl-find-class) (cl-find-class s) "t")))
 
 (defun help--symbol-completion-table-affixation (completions)
   (mapcar (lambda (c)
@@ -154,7 +156,7 @@ help--symbol-completion-table-affixation
                    (doc (condition-case nil (documentation s) (error nil)))
                    (doc (and doc (substring doc 0 (string-match "\n" doc)))))
               (list c (propertize
-                       (concat (help--symbol-class s) " ") ; prefix separator
+                       (format "%-4s " (help--symbol-class s))
                        'face 'completions-annotations)
                     (if doc (propertize (format " -- %s" doc)
                                         'face 'completions-annotations)

Re: [ELPA] New package: marginalia

[Juri Linkov]

>> What about adding the extended `symbol-class` function from Marginalia
>> directly to help-fns.el? Note that the Marginalia function returns
>> multiple characters "fv" if a symbol denotes both a function and a variable.
>>
>> Do you want to keep the `symbol-class` to be a single character under
>> all circumstances?
>
> I have tried to use marginalia--symbol-class for help--symbol-class,
> and noticed a few problems:
>
> 1. It's hard to visually scan the column with types
>    when the primary char (f, c, v, u) is not the first in the row.
>    In the following patch I moved the primary char to the beginning.
>
> 2. Also it would help to see the letter of the primary char
>    if secondary chars are not letters.  So I replaced "o" (obsolete)
>    with a strikethrough symbol "-".
>
> 3. Are Unicode characters allowed?  Then could we add to the primary char
>    e.g. COMBINING LONG STROKE OVERLAY (U+0336) to designate obsolete.
>
> 4. The remaining secondary letter is "l" for local, but I can't find
>    a non-letter character to replace it.

A good character would be a prime like in derivatives, e.g. v' and u'.
I guess this is ok, so pushed to master.  Please respond if you disagree.

> 5. Isn't using formatting such as "%-6s" not suitable in the backend?
>    At least, I moved it out of help--symbol-class.  Ideally,
>    the frontend should adjust column sizes to fit them to the longest value.
>
> 6. The format "%-6s " with 7 placeholders that is too wide for most symbols
>    when a tiny fraction of symbols has 4 chars max, so reduced it to 4:

Re: [ELPA] New package: marginalia

[Jens C. Jensen]

> From: Juri Linkov <juri@linkov.net>
> Date: Tue, 01 Jun 2021 23:54:45 +0300

> Maybe something like [...]
>
> Then you could use it, and prepend/append more characters
> such as: o for obsolete, ! for advised, * for modified.

I was recently fiddling with my configuration and was surprised not to find this function anywhere, so this would be a welcome addition in my opinion.

I too stumbled on `help--symbol-completion-table-affixation', however it seems to specialize on function-symbols (function/macro/command), but not on variables (keymap/boolean/keyword/etc.).

I ended up with something like:
#+begin_src emacs-lisp
(cond
 ((commandp sym) 'command)
 ((macrop sym) 'macro)
 ((functionp sym) 'function)
 ((booleanp sym) 'boolean)
 ((keywordp sym) 'keyword)
 ((keymapp (symbol-value sym)) 'keymap)
 ((facep sym) 'face)
 ((boundp sym) 'variable)
 ((symbolp sym) 'symbol))
#+end_src

It has worked fine for my use-case thus far, but is neither complete nor robust enough for documentation, as Daniel pointed out emacs-lisp is a Lisp-2 - the above code completely misses this point.

Re: [ELPA] New package: marginalia

[Daniel Mendler]

On 6/2/21 4:46 PM, Jens C. Jensen wrote:
> I ended up with something like:
> #+begin_src emacs-lisp
> (cond
>  ((commandp sym) 'command)
>  ((macrop sym) 'macro)
>  ((functionp sym) 'function)
>  ((booleanp sym) 'boolean)
>  ((keywordp sym) 'keyword)
>  ((keymapp (symbol-value sym)) 'keymap)
>  ((facep sym) 'face)
>  ((boundp sym) 'variable)
>  ((symbolp sym) 'symbol))
> #+end_src
> 
> It has worked fine for my use-case thus far, but is neither complete nor robust enough for documentation, as Daniel pointed out emacs-lisp is a Lisp-2 - the above code completely misses this point.

Yes exactly, such a classifier should return a list of types. The
Marginalia symbol annotator gets this right and annotates each symbol
with multiple characters. I like this annotation functionality when
doing Elisp hacking. Also `marginalia-annotate-variable` is quite useful.

Jens, where are you using this classifier in your configuration?

Daniel

Re: [ELPA] New package: marginalia

[Jens C. Jensen]

> From: Daniel Mendler <mail@daniel-mendler.de>
> Date: Wed, 02 Jun 2021 17:07:54 +0200
>
> Jens, where are you using this classifier in your configuration?

I've used it for annotating elisp symbols when completing, which coincidentally sounds like something that marginalia also does.

I've been meaning to compare my current configuration to some combination of the built-in solutions (icomplete/fido), since there has been a lot of work recently with their vertical modes, and the vertico/marginalia/embark/consult "stack", mainly because my current ivy config is becoming rather big (ivy+swiper+counsel itself is 12k~ LOC)

Re: [ELPA] New package: marginalia

[Stefan Monnier]

> #+begin_src emacs-lisp
> (cond
>  ((commandp sym) 'command)
>  ((macrop sym) 'macro)
>  ((functionp sym) 'function)
>  ((booleanp sym) 'boolean)
>  ((keywordp sym) 'keyword)
>  ((keymapp (symbol-value sym)) 'keymap)
>  ((facep sym) 'face)
>  ((boundp sym) 'variable)
>  ((symbolp sym) 'symbol))
> #+end_src
>
> It has worked fine for my use-case thus far, but is neither complete nor
> robust enough for documentation, as Daniel pointed out emacs-lisp is
> a Lisp-2 - the above code completely misses this point.

Not just "2": `facep` shows there's more than 2 namespaces.


        Stefan