README-elpa (11434B)
1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2 MARGINALIA.EL - MARGINALIA IN THE MINIBUFFER 3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4 5 6 This package provides `marginalia-mode' which adds marginalia to the 7 minibuffer completions. [Marginalia] are marks or annotations placed at 8 the margin of the page of a book or in this case helpful colorful 9 annotations placed at the margin of the minibuffer for your completion 10 candidates. Marginalia can only add annotations to the completion 11 candidates. It cannot modify the appearance of the candidates 12 themselves, which are shown unaltered as supplied by the original 13 command. 14 15 The annotations are added based on the completion category. For example 16 `find-file' reports the `file' category and `M-x' reports the `command' 17 category. You can cycle between more or less detailed annotators or even 18 disable the annotator with command `marginalia-cycle'. 19 20 Table of Contents 21 ───────────────── 22 23 1. Configuration 24 2. Information shown by the annotators 25 3. Adding custom annotators or classifiers 26 4. Disabling annotators, builtin or lightweight annotators 27 5. Icons in the minibuffer 28 6. Contributions 29 30 31 [Marginalia] <https://en.wikipedia.org/wiki/Marginalia> 32 33 34 1 Configuration 35 ═══════════════ 36 37 It is recommended to use Marginalia together with either the 38 [Vertico], [Mct], [Icomplete] or the default completion 39 UI. Furthermore Marginalia can be combined with [Embark] for action 40 support and [Consult], which provides many useful commands. 41 42 ┌──── 43 │ ;; Enable rich annotations using the Marginalia package 44 │ (use-package marginalia 45 │ ;; Bind `marginalia-cycle' locally in the minibuffer. To make the binding 46 │ ;; available in the *Completions* buffer, add it to the 47 │ ;; `completion-list-mode-map'. 48 │ :bind (:map minibuffer-local-map 49 │ ("M-A" . marginalia-cycle)) 50 │ 51 │ ;; The :init section is always executed. 52 │ :init 53 │ 54 │ ;; Marginalia must be activated in the :init section of use-package such that 55 │ ;; the mode gets enabled right away. Note that this forces loading the 56 │ ;; package. 57 │ (marginalia-mode)) 58 └──── 59 60 61 [Vertico] <https://github.com/minad/vertico> 62 63 [Mct] <https://github.com/protesilaos/mct> 64 65 [Icomplete] 66 <https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html> 67 68 [Embark] <https://github.com/oantolin/embark> 69 70 [Consult] <https://github.com/minad/consult> 71 72 73 2 Information shown by the annotators 74 ═════════════════════════════════════ 75 76 In general, to learn more about what different annotations mean, a 77 good starting point is to look at `marginalia-annotator-registry', and 78 follow up to the annotation function of the category you are 79 interested in. 80 81 For example the annotations for Elisp symbols include their symbol 82 class - `v' for variable, `f' for function, `c' for command, etc. For 83 more information on what the different classifications mean, see the 84 docstring of `marginalia--symbol-class'. 85 86 87 3 Adding custom annotators or classifiers 88 ═════════════════════════════════════════ 89 90 *IMPORTANT NOTICE FOR PACKAGE AUTHORS*: The intention of the 91 Marginalia package is to give the user means to overwrite completion 92 categories and to add custom annotators for existing commands in their 93 user configuration. *Marginalia is a user facing package and is not 94 intended to be used as a library*. Therefore Marginalia does not 95 expose library functions as part of its public API. If you add your 96 own completion commands to your package we recommend to specify an 97 `annotation-function' or an `affixation-function', avoiding the 98 Marginalia dependency this way. The `annotation-function' and 99 `affixation-function' are documented in the [Elisp manual]. If you use 100 `consult--read', you can specify an `:annotate' keyword 101 argument. There is an exception to our recommendation: If you want to 102 implement annotations for an existing package `hypothetic.el', which 103 does not have annotations and where annotations cannot be added, then 104 the creation of a `marginalia-hypothetic.el' package is a good idea, 105 since Marginalia provides the facilities to enhance existing commands 106 from the outside. If you have questions feel free to ask on the 107 Marginalia issue tracker. 108 109 Commands that support minibuffer completion use a completion table of 110 all the available candidates. Candidates are associated with a 111 *category* such as `command', `file', `face', or `variable' depending 112 on what the candidates are. Based on the category of the candidates, 113 Marginalia selects an *annotator* to generate annotations for display 114 for each candidate. 115 116 Unfortunately, not all commands (including Emacs' builtin ones) 117 specify the category of their candidates. To compensate for this 118 shortcoming, Marginalia hooks into the Emacs completion framework and 119 runs the *classifiers* listed in the variable 120 `marginalia-classifiers', which use the command's prompt or other 121 properties of the candidates to specify the completion category. 122 123 For example, the `marginalia-classify-by-prompt' classifier checks the 124 minibuffer prompt against regexps listed in the 125 `marginalia-prompt-categories' alist to determine a category. The 126 following is already included but would be a way to assign the 127 category `face' to all candidates from commands with prompts that 128 include the word "face". 129 130 ┌──── 131 │ (add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face)) 132 └──── 133 134 The `marginalia-classify-by-command-name' classifier uses the alist 135 `marginalia-command-categories' to specify the completion category 136 based on the command name. This is particularly useful if the prompt 137 classifier yields a false positive. 138 139 Completion categories are also important for [Embark], which 140 associates actions based on the completion category and benefits from 141 Marginalia's classifiers. 142 143 Once the category of the candidates is known, Marginalia looks in the 144 `marginalia-annotator-registry' to find the associated annotator to 145 use. An annotator is a function that takes a completion candidate 146 string as an argument and returns an annotation string to be displayed 147 after the candidate in the minibuffer. More than one annotator can be 148 assigned to each each category, displaying more, less or different 149 information. Use the `marginalia-cycle' command to cycle between the 150 annotations of different annotators defined for the current category. 151 152 Here's an example of a basic face annotator: 153 154 ┌──── 155 │ (defun my-face-annotator (cand) 156 │ (when-let (sym (intern-soft cand)) 157 │ (concat (propertize " " 'display '(space :align-to center)) 158 │ (propertize "The quick brown fox jumps over the lazy dog" 'face sym)))) 159 └──── 160 161 Look at Marginalia's various annotators for examples of formatting 162 annotations. In particular, the helper function `marginalia--fields' 163 can be used to format information into columns. 164 165 After defining a new annotator, associate it with a category in the 166 annotator registry as follows: 167 168 ┌──── 169 │ (add-to-list 'marginalia-annotator-registry 170 │ '(face my-face-annotator marginalia-annotate-face builtin none)) 171 └──── 172 173 This makes the `my-face-annotator' the first of four annotators for 174 the face category. The others are the annotator provided by Marginalia 175 (`marginalia-annotate-face'), the `builtin' annotator as defined by 176 Emacs and the `none' annotator, which disables the annotations. With 177 this setting, after invoking `M-x describe-face RET' you can cycle 178 between all of these annotators using `marginalia-cycle'. 179 180 181 [Elisp manual] 182 <https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html> 183 184 [Embark] <https://github.com/oantolin/embark> 185 186 187 4 Disabling annotators, builtin or lightweight annotators 188 ═════════════════════════════════════════════════════════ 189 190 Marginalia activates rich annotators by default. Depending on your 191 preference you may want to use the builtin annotators or even no 192 annotators by default and only activate the annotators on demand by 193 invoking `marginalia-cycle'. 194 195 In order to use the builtin annotators by default, you can use the 196 following command. Replace `builtin' by `none' to disable annotators 197 by default. 198 199 ┌──── 200 │ (defun marginalia-use-builtin () 201 │ (interactive) 202 │ (mapc 203 │ (lambda (x) 204 │ (setcdr x (cons 'builtin (remq 'builtin (cdr x))))) 205 │ marginalia-annotator-registry)) 206 └──── 207 208 If a completion category supports two annotators, you can toggle 209 between those using this command. 210 211 ┌──── 212 │ (defun marginalia-toggle () 213 │ (interactive) 214 │ (mapc 215 │ (lambda (x) 216 │ (setcdr x (append (reverse (remq 'none 217 │ (remq 'builtin (cdr x)))) 218 │ '(builtin none)))) 219 │ marginalia-annotator-registry)) 220 └──── 221 222 After cycling the annotators you may want to automatically save the 223 configuration. This can be achieved using an advice which calls 224 `customize-save-variable'. 225 226 ┌──── 227 │ (advice-add #'marginalia-cycle :after 228 │ (lambda () 229 │ (let ((inhibit-message t)) 230 │ (customize-save-variable 'marginalia-annotator-registry 231 │ marginalia-annotator-registry)))) 232 └──── 233 234 In order to disable an annotator permanently, the 235 `marginalia-annotator-registry' can be modified. For example if you 236 prefer to never see file annotations, you can delete all file 237 annotators from the registry. 238 239 ┌──── 240 │ (setq marginalia-annotator-registry 241 │ (assq-delete-all 'file marginalia-annotator-registry)) 242 └──── 243 244 245 5 Icons in the minibuffer 246 ═════════════════════════ 247 248 Icons in the minibuffer completion UI are a commonly requested 249 feature. Marginalia focuses on text annotations only. The following 250 packages are compatible with Marginalia and use special fonts to add 251 icons in front of completion candidates. There also exist related 252 packages to enhance Dired, Ibuffer and other modes with icons 253 consistently. 254 255 • [all-the-icons-completion]: Relies on the `all-the-icons.el' package 256 which configures multiple icon fonts. 257 • [nerd-icons-completion]: Relies on patched fonts including 258 icons. This package works even in the terminal where only a single 259 font can be used. 260 261 262 [all-the-icons-completion] 263 <https://github.com/iyefrat/all-the-icons-completion> 264 265 [nerd-icons-completion] 266 <https://github.com/rainstormstudio/nerd-icons-completion> 267 268 269 6 Contributions 270 ═══════════════ 271 272 Since this package is part of [GNU ELPA] contributions require a 273 copyright assignment to the FSF. 274 275 276 [GNU ELPA] <https://elpa.gnu.org/packages/marginalia.html>