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