README.org (10190B)
1 #+title: marginalia.el - Marginalia in the minibuffer 2 #+author: Omar Antolín Camarena, Daniel Mendler 3 #+language: en 4 #+export_file_name: marginalia.texi 5 #+texinfo_dir_category: Emacs misc features 6 #+texinfo_dir_title: Marginalia: (marginalia). 7 #+texinfo_dir_desc: Marginalia in the minibuffer 8 9 #+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a> 10 #+html: <a href="https://elpa.gnu.org/packages/marginalia.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/marginalia.svg"/></a> 11 #+html: <a href="https://elpa.gnu.org/devel/marginalia.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/marginalia.svg"/></a> 12 #+html: <a href="https://melpa.org/#/marginalia"><img alt="MELPA" src="https://melpa.org/packages/marginalia-badge.svg"/></a> 13 #+html: <a href="https://stable.melpa.org/#/marginalia"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/marginalia-badge.svg"/></a> 14 15 #+html: <img src="https://upload.wikimedia.org/wikipedia/commons/4/4f/Marginalia_%285095211566%29.jpg" align="right" width="30%"> 16 17 This package provides =marginalia-mode= which adds marginalia to the minibuffer 18 completions. [[https://en.wikipedia.org/wiki/Marginalia][Marginalia]] are marks or annotations placed at the margin of the 19 page of a book or in this case helpful colorful annotations placed at the margin 20 of the minibuffer for your completion candidates. Marginalia can only add 21 annotations to the completion candidates. It cannot modify the appearance of the 22 candidates themselves, which are shown unaltered as supplied by the original 23 command. 24 25 The annotations are added based on the completion category. For example 26 =find-file= reports the =file= category and =M-x= reports the =command= category. You 27 can cycle between more or less detailed annotators or even disable the annotator 28 with command =marginalia-cycle=. 29 30 #+html: <img src="https://github.com/minad/marginalia/blob/screenshots/marginalia-mode.png?raw=true"> 31 32 #+toc: headlines 8 33 34 * Configuration 35 36 It is recommended to use Marginalia together with either the [[https://github.com/minad/vertico][Vertico]], [[https://github.com/protesilaos/mct][Mct]], 37 [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]] or the default completion UI. Furthermore Marginalia can be combined 38 with [[https://github.com/oantolin/embark][Embark]] for action support and [[https://github.com/minad/consult][Consult]], which provides many useful commands. 39 40 #+begin_src emacs-lisp 41 ;; Enable rich annotations using the Marginalia package 42 (use-package marginalia 43 ;; Either bind `marginalia-cycle' globally or only in the minibuffer 44 :bind (("M-A" . marginalia-cycle) 45 :map minibuffer-local-map 46 ("M-A" . marginalia-cycle)) 47 48 ;; The :init configuration is always executed (Not lazy!) 49 :init 50 51 ;; Must be in the :init section of use-package such that the mode gets 52 ;; enabled right away. Note that this forces loading the package. 53 (marginalia-mode)) 54 #+end_src 55 56 * Information shown by the annotators 57 58 In general, to learn more about what different annotations mean, a good starting 59 point is to look at ~marginalia-annotator-registry~, and follow up to the 60 annotation function of the category you are interested in. 61 62 For example the annotations for Elisp symbols include their symbol class - =v= for 63 variable, =f= for function, =c= for command, etc. For more information on what the 64 different classifications mean, see the docstring of ~marginalia--symbol-class~. 65 66 * Adding custom annotators or classifiers 67 68 *IMPORTANT NOTICE FOR PACKAGE AUTHORS*: The intention of the Marginalia package is 69 to give the user means to overwrite completion categories and to add custom 70 annotators for existing commands in their user configuration. *Marginalia is a 71 user facing package and is not intended to be used as a library*. Therefore 72 Marginalia does not expose library functions as part of its public API. If you 73 add your own completion commands to your package we recommend to specify an 74 =annotation-function= or an =affixation-function=, avoiding the Marginalia 75 dependency this way. The =annotation-function= and =affixation-function= are 76 documented in the [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html][Elisp manual]]. If you use =consult--read=, you can specify an 77 =:annotate= keyword argument. There is an exception to our recommendation: If you 78 want to implement annotations for an existing package =hypothetic.el=, which does 79 not have annotations and where annotations cannot be added, then the creation of 80 a =marginalia-hypothetic.el= package is a good idea, since Marginalia provides the 81 facilities to enhance existing commands from the outside. If you have questions 82 feel free to ask on the Marginalia issue tracker. 83 84 Commands that support minibuffer completion use a completion table of all the 85 available candidates. Candidates are associated with a *category* such as =command=, 86 =file=, =face=, or =variable= depending on what the candidates are. Based on the 87 category of the candidates, Marginalia selects an *annotator* to generate 88 annotations for display for each candidate. 89 90 Unfortunately, not all commands (including Emacs' builtin ones) specify the 91 category of their candidates. To compensate for this shortcoming, Marginalia 92 hooks into the Emacs completion framework and runs the *classifiers* listed in the 93 variable =marginalia-classifiers=, which use the command's prompt or other 94 properties of the candidates to specify the completion category. 95 96 For example, the =marginalia-classify-by-prompt= classifier checks the minibuffer 97 prompt against regexps listed in the =marginalia-prompt-categories= alist to 98 determine a category. The following is already included but would be a way to 99 assign the category =face= to all candidates from commands with prompts that 100 include the word "face". 101 102 #+begin_src emacs-lisp 103 (add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face)) 104 #+end_src 105 106 The =marginalia-classify-by-command-name= classifier uses the alist 107 =marginalia-command-categories= to specify the completion category based on the 108 command name. This is particularly useful if the prompt classifier yields a 109 false positive. 110 111 Completion categories are also important for [[https://github.com/oantolin/embark][Embark]], which associates actions 112 based on the completion category and benefits from Marginalia's classifiers. 113 114 Once the category of the candidates is known, Marginalia looks in the 115 =marginalia-annotator-registry= to find the associated annotator to use. An 116 annotator is a function that takes a completion candidate string as an argument 117 and returns an annotation string to be displayed after the candidate in the 118 minibuffer. More than one annotator can be assigned to each each category, 119 displaying more, less or different information. Use the =marginalia-cycle= command 120 to cycle between the annotations of different annotators defined for the current 121 category. 122 123 Here's an example of a basic face annotator: 124 125 #+begin_src emacs-lisp 126 (defun my-face-annotator (cand) 127 (when-let (sym (intern-soft cand)) 128 (concat (propertize " " 'display '(space :align-to center)) 129 (propertize "The quick brown fox jumps over the lazy dog" 'face sym)))) 130 #+end_src 131 132 Look at Marginalia's various annotators for examples of formatting annotations. 133 In particular, the helper function =marginalia--fields= can be used to format 134 information into columns. 135 136 After defining a new annotator, associate it with a category in the annotator 137 registry as follows: 138 139 #+begin_src emacs-lisp 140 (add-to-list 'marginalia-annotator-registry 141 '(face my-face-annotator marginalia-annotate-face builtin none)) 142 #+end_src 143 144 This makes the =my-face-annotator= the first of four annotators for the face 145 category. The others are the annotator provided by Marginalia 146 (=marginalia-annotate-face=), the =builtin= annotator as defined by Emacs and the 147 =none= annotator, which disables the annotations. With this setting, after 148 invoking =M-x describe-face RET= you can cycle between all of these annotators 149 using =marginalia-cycle=. 150 151 * Disabling annotators, builtin or lightweight annotators 152 153 Marginalia activates rich annotators by default. Depending on your preference 154 you may want to use the builtin annotators or even no annotators by default and 155 only activate the annotators on demand by invoking ~marginalia-cycle~. 156 157 In order to use the builtin annotators by default, you can use the following 158 command. Replace =builtin= by =none= to disable annotators by default. 159 160 #+begin_src emacs-lisp 161 (defun marginalia-use-builtin () 162 (interactive) 163 (mapc 164 (lambda (x) 165 (setcdr x (cons 'builtin (remq 'builtin (cdr x))))) 166 marginalia-annotator-registry)) 167 #+end_src 168 169 If a completion category supports two annotators, you can toggle between 170 those using this command. 171 172 #+begin_src emacs-lisp 173 (defun marginalia-toggle () 174 (interactive) 175 (mapc 176 (lambda (x) 177 (setcdr x (append (reverse (remq 'none 178 (remq 'builtin (cdr x)))) 179 '(builtin none)))) 180 marginalia-annotator-registry)) 181 #+end_src 182 183 After cycling the annotators you may want to automatically save the 184 configuration. This can be achieved using an advice which calls 185 ~customize-save-variable~. 186 187 #+begin_src emacs-lisp 188 (advice-add #'marginalia-cycle :after 189 (lambda () 190 (let ((inhibit-message t)) 191 (customize-save-variable 'marginalia-annotator-registry 192 marginalia-annotator-registry)))) 193 #+end_src 194 195 In order to disable an annotator permanently, the ~marginalia-annotator-registry~ 196 can be modified. For example if you prefer to never see file annotations, you 197 can delete all file annotators from the registry. 198 199 #+begin_src emacs-lisp 200 (setq marginalia-annotator-registry 201 (assq-delete-all 'file marginalia-annotator-registry)) 202 #+end_src 203 204 * Contributions 205 206 Since this package is part of [[https://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions require a copyright 207 assignment to the FSF.