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