[elpa] externals/marginalia 43c85dc 229/241: README: More documentation

[Stefan Monnier]

branch: externals/marginalia
commit 43c85dcb341b8036ca3b56197ab0644cd4627a39
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    README: More documentation
---
 README.org      | 38 +++++++++++++++++++++++++++-----------
 marginalia.texi | 38 +++++++++++++++++++++++++++-----------
 2 files changed, 54 insertions(+), 22 deletions(-)

diff --git a/README.org b/README.org
index 855c287..5a10933 100644
--- a/README.org
+++ b/README.org
@@ -65,23 +65,39 @@ commands.
 
 * Using builtin or lightweight annotators
 
-Marginalia activates visually heavy annotators by default. Depending on your
-preference you may want to use the builtin annotators or even no annotators by
-default and only activate the annotators on demand by invoking
-~marginalia-cycle~.
+Marginalia activates rich annotators by default. Depending on your preference
+you may want to use the builtin annotators or even no annotators by default and
+only activate the annotators on demand by invoking ~marginalia-cycle~.
 
 In order to use the builtin annotators by default, you can use the following
-snippet. Replace =builtin= by =none= to disable annotators by default.
+command. Replace =builtin= by =none= to disable annotators by default.
 
 #+begin_src emacs-lisp
-  (mapc
-   (lambda (x) (setcdr x (cons 'builtin (delete 'builtin (cdr x)))))
-   marginalia-annotator-registry)
+  (defun marginalia-use-builtin ()
+    (interactive)
+    (mapc
+     (lambda (x)
+       (setcdr x (cons 'builtin (delq 'builtin (cdr x)))))
+     marginalia-annotator-registry))
 #+end_src
 
-After having cycled the annotators you may want to automatically save the
-annotator configuration. This can be achieved using an advice which calls
-~customize-save-variable~:
+If a completion category supports two annotators, you can toggle between
+those using this command.
+
+#+begin_src emacs-lisp
+  (defun marginalia-toggle ()
+    (interactive)
+    (mapc
+     (lambda (x)
+       (setcdr x (append (nreverse (delq 'none
+                                         (delq 'builtin (cdr x))))
+                         '(builtin none))))
+     marginalia-annotator-registry))
+#+end_src
+
+After cycling the annotators you may want to automatically save the
+configuration. This can be achieved using an advice which calls
+~customize-save-variable~.
 
 #+begin_src emacs-lisp
   (advice-add #'marginalia-cycle :after
diff --git a/marginalia.texi b/marginalia.texi
index da79e06..2db3767 100644
--- a/marginalia.texi
+++ b/marginalia.texi
@@ -86,23 +86,39 @@ commands.
 @node Using builtin or lightweight annotators
 @chapter Using builtin or lightweight annotators
 
-Marginalia activates visually heavy annotators by default. Depending on your
-preference you may want to use the builtin annotators or even no annotators by
-default and only activate the annotators on demand by invoking
-@code{marginalia-cycle}.
+Marginalia activates rich annotators by default. Depending on your preference
+you may want to use the builtin annotators or even no annotators by default and
+only activate the annotators on demand by invoking @code{marginalia-cycle}.
 
 In order to use the builtin annotators by default, you can use the following
-snippet. Replace @samp{builtin} by @samp{none} to disable annotators by 
default.
+command. Replace @samp{builtin} by @samp{none} to disable annotators by 
default.
 
 @lisp
-(mapc
- (lambda (x) (setcdr x (cons 'builtin (delete 'builtin (cdr x)))))
- marginalia-annotator-registry)
+(defun marginalia-use-builtin ()
+  (interactive)
+  (mapc
+   (lambda (x)
+     (setcdr x (cons 'builtin (delq 'builtin (cdr x)))))
+   marginalia-annotator-registry))
 @end lisp
 
-After having cycled the annotators you may want to automatically save the
-annotator configuration. This can be achieved using an advice which calls
-@code{customize-save-variable}:
+If a completion category supports two annotators, you can toggle between
+those using this command.
+
+@lisp
+(defun marginalia-toggle ()
+  (interactive)
+  (mapc
+   (lambda (x)
+     (setcdr x (append (nreverse (delq 'none
+                                       (delq 'builtin (cdr x))))
+                       '(builtin none))))
+   marginalia-annotator-registry))
+@end lisp
+
+After cycling the annotators you may want to automatically save the
+configuration. This can be achieved using an advice which calls
+@code{customize-save-variable}.
 
 @lisp
 (advice-add #'marginalia-cycle :after