marginalia.info (10862B)
1 This is doc7iS3dD.info, produced by makeinfo version 6.7 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: doc7iS3dD.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 * Contributions:: 38 39 40 File: doc7iS3dD.info, Node: Configuration, Next: Information shown by the annotators, Prev: Top, Up: Top 41 42 1 Configuration 43 *************** 44 45 It is recommended to use Marginalia together with either the Vertico 46 (https://github.com/minad/vertico), Mct 47 (https://github.com/protesilaos/mct), Icomplete 48 (https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html) 49 or the default completion UI. Furthermore Marginalia can be combined 50 with Embark (https://github.com/oantolin/embark) for action support and 51 Consult (https://github.com/minad/consult), which provides many useful 52 commands. 53 54 ;; Enable rich annotations using the Marginalia package 55 (use-package marginalia 56 ;; Either bind `marginalia-cycle' globally or only in the minibuffer 57 :bind (("M-A" . marginalia-cycle) 58 :map minibuffer-local-map 59 ("M-A" . marginalia-cycle)) 60 61 ;; The :init configuration is always executed (Not lazy!) 62 :init 63 64 ;; Must be in the :init section of use-package such that the mode gets 65 ;; enabled right away. Note that this forces loading the package. 66 (marginalia-mode)) 67 68 69 File: doc7iS3dD.info, Node: Information shown by the annotators, Next: Adding custom annotators or classifiers, Prev: Configuration, Up: Top 70 71 2 Information shown by the annotators 72 ************************************* 73 74 In general, to learn more about what different annotations mean, a good 75 starting point is to look at ‘marginalia-annotator-registry’, and follow 76 up to the annotation function of the category you are 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 File: doc7iS3dD.info, Node: Adding custom annotators or classifiers, Next: Disabling annotators builtin or lightweight annotators, Prev: Information shown by the annotators, Up: Top 85 86 3 Adding custom annotators or classifiers 87 ***************************************** 88 89 *IMPORTANT NOTICE FOR PACKAGE AUTHORS*: The intention of the Marginalia 90 package is to give the user means to overwrite completion categories and 91 to add custom annotators for existing commands in their user 92 configuration. *Marginalia is a user facing package and is not intended 93 to be used as a library*. Therefore Marginalia does not expose library 94 functions as part of its public API. If you add your own completion 95 commands to your package we recommend to specify an 96 ‘annotation-function’ or an ‘affixation-function’, avoiding the 97 Marginalia dependency this way. The ‘annotation-function’ and 98 ‘affixation-function’ are documented in the Elisp manual 99 (https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html). 100 If you use ‘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 on 112 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 ‘marginalia-classifiers’, 120 which use the command’s prompt or other properties of the candidates to 121 specify the completion category. 122 123 For example, the ‘marginalia-classify-by-prompt’ classifier checks 124 the 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 category 127 ‘face’ to all candidates from commands with prompts that include the 128 word "face". 129 130 (add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face)) 131 132 The ‘marginalia-classify-by-command-name’ classifier uses the alist 133 ‘marginalia-command-categories’ to specify the completion category based 134 on the command name. This is particularly useful if the prompt 135 classifier yields a false positive. 136 137 Completion categories are also important for Embark 138 (https://github.com/oantolin/embark), which associates actions based on 139 the completion category and benefits from Marginalia’s classifiers. 140 141 Once the category of the candidates is known, Marginalia looks in the 142 ‘marginalia-annotator-registry’ to find the associated annotator to use. 143 An annotator is a function that takes a completion candidate string as 144 an argument and returns an annotation string to be displayed after the 145 candidate in the minibuffer. More than one annotator can be assigned to 146 each each category, displaying more, less or different information. Use 147 the ‘marginalia-cycle’ command to cycle between the annotations of 148 different annotators defined for the current category. 149 150 Here’s an example of a basic face annotator: 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 Look at Marginalia’s various annotators for examples of formatting 158 annotations. In particular, the helper function ‘marginalia--fields’ 159 can be used to format information into columns. 160 161 After defining a new annotator, associate it with a category in the 162 annotator registry as follows: 163 164 (add-to-list 'marginalia-annotator-registry 165 '(face my-face-annotator marginalia-annotate-face builtin none)) 166 167 This makes the ‘my-face-annotator’ the first of four annotators for 168 the face category. The others are the annotator provided by Marginalia 169 (‘marginalia-annotate-face’), the ‘builtin’ annotator as defined by 170 Emacs and the ‘none’ annotator, which disables the annotations. With 171 this setting, after invoking ‘M-x describe-face RET’ you can cycle 172 between all of these annotators using ‘marginalia-cycle’. 173 174 175 File: doc7iS3dD.info, Node: Disabling annotators builtin or lightweight annotators, Next: Contributions, Prev: Adding custom annotators or classifiers, Up: Top 176 177 4 Disabling annotators, builtin or lightweight annotators 178 ********************************************************* 179 180 Marginalia activates rich annotators by default. Depending on your 181 preference you may want to use the builtin annotators or even no 182 annotators by default and only activate the annotators on demand by 183 invoking ‘marginalia-cycle’. 184 185 In order to use the builtin annotators by default, you can use the 186 following command. Replace ‘builtin’ by ‘none’ to disable annotators by 187 default. 188 189 (defun marginalia-use-builtin () 190 (interactive) 191 (mapc 192 (lambda (x) 193 (setcdr x (cons 'builtin (remq 'builtin (cdr x))))) 194 marginalia-annotator-registry)) 195 196 If a completion category supports two annotators, you can toggle 197 between those using this command. 198 199 (defun marginalia-toggle () 200 (interactive) 201 (mapc 202 (lambda (x) 203 (setcdr x (append (reverse (remq 'none 204 (remq 'builtin (cdr x)))) 205 '(builtin none)))) 206 marginalia-annotator-registry)) 207 208 After cycling the annotators you may want to automatically save the 209 configuration. This can be achieved using an advice which calls 210 ‘customize-save-variable’. 211 212 (advice-add #'marginalia-cycle :after 213 (lambda () 214 (let ((inhibit-message t)) 215 (customize-save-variable 'marginalia-annotator-registry 216 marginalia-annotator-registry)))) 217 218 In order to disable an annotator permanently, the 219 ‘marginalia-annotator-registry’ can be modified. For example if you 220 prefer to never see file annotations, you can delete all file annotators 221 from the registry. 222 223 (setq marginalia-annotator-registry 224 (assq-delete-all 'file marginalia-annotator-registry)) 225 226 227 File: doc7iS3dD.info, Node: Contributions, Prev: Disabling annotators builtin or lightweight annotators, Up: Top 228 229 5 Contributions 230 *************** 231 232 Since this package is part of GNU ELPA 233 (https://elpa.gnu.org/packages/marginalia.html) contributions require a 234 copyright assignment to the FSF. 235 236 237 238 Tag Table: 239 Node: Top216 240 Node: Configuration1450 241 Node: Information shown by the annotators2598 242 Node: Adding custom annotators or classifiers3310 243 Node: Disabling annotators builtin or lightweight annotators8226 244 Node: Contributions10267 245 246 End Tag Table 247 248 249 Local Variables: 250 coding: utf-8 251 End: