branch: externals/marginalia
commit ea65ac9d5dccae5183a2f52e21f5545225a86e28
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
Rename marginalia-annotator-registry to marginalia-annotators
For consistency with marginalia-classifiers. marginalia-annotators was the
old
name a long ago before some format change which required the renaming to
marginalia-annotator-registry.
---
CHANGELOG.org | 5 +++++
README.org | 37 ++++++++++++++++++-------------------
marginalia.el | 17 ++++++++++-------
3 files changed, 33 insertions(+), 26 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index f6f6efb910..d40184a97a 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -2,6 +2,11 @@
#+author: Omar Antolín Camarena, Daniel Mendler
#+language: en
+* Development
+
+- Rename =marginalia-annotator-registry= to =marginalia-annotators= for
consistency
+ with =marginalia-classifiers=.
+
* Version 2.0 (2025-03-17)
- =marginalia--variable-value=: Add tool tip for integers with hexadecimal,
octal
diff --git a/README.org b/README.org
index 255eaa0541..3d6245cefd 100644
--- a/README.org
+++ b/README.org
@@ -58,8 +58,8 @@ with [[https://github.com/oantolin/embark][Embark]] for
action support and [[htt
* Information shown by the annotators
In general, to learn more about what different annotations mean, a good
starting
-point is to look at ~marginalia-annotator-registry~, and follow up to the
-annotation function of the category you are interested in.
+point is to look at ~marginalia-annotators~, and follow up to the annotation
+function of the category you are interested in.
For example the annotations for Elisp symbols include their symbol class - =v=
for
variable, =f= for function, =c= for command, etc. For more information on what
the
@@ -115,13 +115,12 @@ Completion categories are also important for
[[https://github.com/oantolin/embar
based on the completion category and benefits from Marginalia's classifiers.
Once the category of the candidates is known, Marginalia looks in the
-=marginalia-annotator-registry= to find the associated annotator to use. An
-annotator is a function that takes a completion candidate string as an argument
-and returns an annotation string to be displayed after the candidate in the
-minibuffer. More than one annotator can be assigned to each each category,
-displaying more, less or different information. Use the =marginalia-cycle=
command
-to cycle between the annotations of different annotators defined for the
current
-category.
+=marginalia-annotators= to find the associated annotator to use. An annotator
is a
+function that takes a completion candidate string as an argument and returns an
+annotation string to be displayed after the candidate in the minibuffer. More
+than one annotator can be assigned to each each category, displaying more, less
+or different information. Use the =marginalia-cycle= command to cycle between
the
+annotations of different annotators defined for the current category.
Here's an example of a basic face annotator:
@@ -136,7 +135,7 @@ After defining a new annotator, associate it with a
category in the annotator
registry as follows:
#+begin_src emacs-lisp
- (add-to-list 'marginalia-annotator-registry
+ (add-to-list 'marginalia-annotators
'(face my-face-annotator marginalia-annotate-face builtin none))
#+end_src
@@ -153,13 +152,13 @@ Marginalia activates rich annotators by default.
Depending on your preference
you may want to use the builtin annotators or even no annotators by default and
only activate the annotators on demand by invoking ~marginalia-cycle~.
-In order to disable an annotator permanently, the
~marginalia-annotator-registry~
-can be modified. For example if you prefer to never see file annotations, you
-can delete all file annotators from the registry.
+In order to disable an annotator permanently, the ~marginalia-annotators~ can
be
+modified. For example if you prefer to never see file annotations, you can
+delete all file annotators from the registry.
#+begin_src emacs-lisp
- (setq marginalia-annotator-registry
- (assq-delete-all 'file marginalia-annotator-registry))
+ (setq marginalia-annotators
+ (assq-delete-all 'file marginalia-annotators))
#+end_src
To use the builtin annotators by default, you can run the following code.
@@ -168,7 +167,7 @@ Replace =builtin= by =none= to disable annotators by
default.
#+begin_src emacs-lisp
(mapc (lambda (x)
(setcdr x (cons 'builtin (remq 'builtin (cdr x)))))
- marginalia-annotator-registry)
+ marginalia-annotators)
#+end_src
As an alternative to ~marginalia-cycle~, if a completion category supports two
@@ -182,7 +181,7 @@ annotators, you can toggle between them using the following
command.
(setcdr x (append (reverse (remq 'none
(remq 'builtin (cdr x))))
'(builtin none))))
- marginalia-annotator-registry))
+ marginalia-annotators))
#+end_src
After cycling the annotators you may want to automatically save the
@@ -193,8 +192,8 @@ configuration. This can be achieved using an advice which
calls
(advice-add #'marginalia-cycle :after
(lambda ()
(let ((inhibit-message t))
- (customize-save-variable 'marginalia-annotator-registry
- marginalia-annotator-registry))))
+ (customize-save-variable 'marginalia-annotators
+ marginalia-annotators))))
#+end_src
* Icons in the minibuffer
diff --git a/marginalia.el b/marginalia.el
index d56a4be4b1..56529ed8b6 100644
--- a/marginalia.el
+++ b/marginalia.el
@@ -84,7 +84,10 @@ attribute information. For Tramp paths, the protocol is
displayed instead."
:type '(repeat regexp))
-(defcustom marginalia-annotator-registry
+(define-obsolete-variable-alias 'marginalia-annotator-registry
+ 'marginalia-annotators "2.0")
+
+(defcustom marginalia-annotators
(mapcar
(lambda (x) (append x '(builtin none)))
`((command ,#'marginalia-annotate-command ,#'marginalia-annotate-binding)
@@ -159,9 +162,9 @@ matched case-sensitively."
:type '(repeat (choice symbol regexp)))
(defcustom marginalia-command-categories
- '((imenu . imenu)
- (recentf-open . file)
- (where-is . command))
+ `((,#'imenu . imenu)
+ (,'recentf-open . file) ;; Available only on Emacs 29.
+ (,#'where-is . command))
"Associate commands with a completion category.
The value of `this-command' is used as key for the lookup."
:type '(alist :key-type symbol :value-type symbol))
@@ -449,7 +452,7 @@ Otherwise stay within current buffer."
(defun marginalia--annotator (cat)
"Return annotation function for category CAT."
- (pcase (car (alist-get cat marginalia-annotator-registry))
+ (pcase (car (alist-get cat marginalia-annotators))
('none #'ignore)
('builtin nil)
(fun fun)))
@@ -1344,7 +1347,7 @@ Remember `this-command' for
`marginalia-classify-by-command-name'."
;;;###autoload
(defun marginalia-cycle ()
- "Cycle between annotators in `marginalia-annotator-registry'."
+ "Cycle between annotators in `marginalia-annotators'."
;; Only show `marginalia-cycle' in M-x in recursive minibuffers
(declare (completion (lambda (&rest _) (> (minibuffer-depth) 1))))
(interactive)
@@ -1358,7 +1361,7 @@ Remember `this-command' for
`marginalia-classify-by-command-name'."
minibuffer-completion-predicate))
(cat (or (completion-metadata-get md 'category)
(user-error "Marginalia: Unknown completion category")))
- (ann (or (assq cat marginalia-annotator-registry)
+ (ann (or (assq cat marginalia-annotators)
(user-error "Marginalia: No annotators found for category
`%s'" cat))))
(marginalia--cache-reset)
(setcdr ann (append (cddr ann) (list (cadr ann))))
