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